fast-xml-parser 5.5.7 → 5.5.8

package/lib/pem.d.cts

@@ -0,0 +1,148 @@
+/**
+ * Types copied from path-expression-matcher
+ * @version <version>
+ * @updated <date>
+ *
+ * Update this file when path-expression-matcher releases a new version.
+ * Source: https://github.com/NaturalIntelligence/path-expression-matcher
+ */
+
+/**
+ * Options for creating an Expression
+ */
+interface ExpressionOptions {
+  /**
+   * Path separator character
+   * @default '.'
+   */
+  separator?: string;
+}
+
+/**
+ * Parsed segment from an expression pattern
+ */
+interface Segment {
+  type: 'tag' | 'deep-wildcard';
+  tag?: string;
+  namespace?: string;
+  attrName?: string;
+  attrValue?: string;
+  position?: 'first' | 'last' | 'odd' | 'even' | 'nth';
+  positionValue?: number;
+}
+
+/**
+ * Expression - Parses and stores a tag pattern expression.
+ * Patterns are parsed once and stored in an optimized structure for fast matching.
+ *
+ * @example
+ * ```typescript
+ * const expr = new Expression("root.users.user");
+ * const expr2 = new Expression("..user[id]:first");
+ * const expr3 = new Expression("root/users/user", { separator: '/' });
+ * ```
+ *
+ * Pattern Syntax:
+ * - `root.users.user`      — Match exact path
+ * - `..user`               — Match "user" at any depth (deep wildcard)
+ * - `user[id]`             — Match user tag with "id" attribute
+ * - `user[id=123]`         — Match user tag where id="123"
+ * - `user:first`           — Match first occurrence of user tag
+ * - `ns::user`             — Match user tag with namespace "ns"
+ * - `ns::user[id]:first`   — Combine namespace, attribute, and position
+ */
+declare class Expression {
+  readonly pattern: string;
+  readonly separator: string;
+  readonly segments: Segment[];
+
+  constructor(pattern: string, options?: ExpressionOptions);
+
+  get length(): number;
+  hasDeepWildcard(): boolean;
+  hasAttributeCondition(): boolean;
+  hasPositionSelector(): boolean;
+  toString(): string;
+}
+
+// ---------------------------------------------------------------------------
+// ReadonlyMatcher
+// ---------------------------------------------------------------------------
+
+/**
+ * A live read-only view of a Matcher instance, returned by Matcher.readOnly().
+ *
+ * All query and inspection methods work normally and always reflect the current
+ * state of the underlying matcher. State-mutating methods (`push`, `pop`,
+ * `reset`, `updateCurrent`, `restore`) are not present — calling them on the
+ * underlying Proxy throws a `TypeError` at runtime.
+ *
+ * This is the type received by all FXP user callbacks when `jPath: false`.
+ */
+interface ReadonlyMatcher {
+  readonly separator: string;
+
+  /** Check if current path matches an Expression. */
+  matches(expression: Expression): boolean;
+
+  /** Get current tag name, or `undefined` if path is empty. */
+  getCurrentTag(): string | undefined;
+
+  /** Get current namespace, or `undefined` if not present. */
+  getCurrentNamespace(): string | undefined;
+
+  /** Get attribute value of the current node. */
+  getAttrValue(attrName: string): any;
+
+  /** Check if the current node has a given attribute. */
+  hasAttr(attrName: string): boolean;
+
+  /** Sibling position of the current node (child index in parent). */
+  getPosition(): number;
+
+  /** Occurrence counter of the current tag name at this level. */
+  getCounter(): number;
+
+  /** Number of nodes in the current path. */
+  getDepth(): number;
+
+  /** Current path as a string (e.g. `"root.users.user"`). */
+  toString(separator?: string, includeNamespace?: boolean): string;
+
+  /** Current path as an array of tag names. */
+  toArray(): string[];
+
+  /**
+   * Create a snapshot of the current state.
+   * The snapshot can be passed to the real Matcher.restore() if needed.
+   */
+  snapshot(): MatcherSnapshot;
+}
+
+/** Internal node structure — exposed via snapshot only. */
+interface PathNode {
+  tag: string;
+  namespace?: string;
+  position: number;
+  counter: number;
+  values?: Record<string, any>;
+}
+
+/** Snapshot of matcher state returned by `snapshot()` and `readOnly().snapshot()`. */
+interface MatcherSnapshot {
+  path: PathNode[];
+  siblingStacks: Map<string, number>[];
+}
+
+declare namespace pem {
+  export {
+    Expression,
+    ExpressionOptions,
+    Segment,
+    ReadonlyMatcher,
+    PathNode,
+    MatcherSnapshot,
+  }
+}
+
+export = pem;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fast-xml-parser",
-  "version": "5.5.7",
+  "version": "5.5.8",
   "description": "Validate XML, Parse XML, Build XML without C/C++ based libraries",
   "main": "./lib/fxp.cjs",
   "type": "module",
@@ -88,7 +88,7 @@
   ],
   "dependencies": {
     "fast-xml-builder": "^1.1.4",
-    "path-expression-matcher": "^1.1.3",
+    "path-expression-matcher": "^1.2.0",
     "strnum": "^2.2.0"
   }
 }

package/src/fxp.d.ts

@@ -1,7 +1,9 @@
-//import type { Matcher, Expression } from 'path-expression-matcher';
+import type { Expression, ReadonlyMatcher } from './pem';
 
-type Matcher = unknown;
-type Expression = unknown;
+// jPath: true  → string
+// jPath: false → ReadonlyMatcher
+type JPathOrMatcher = string | ReadonlyMatcher;
+type JPathOrExpression = string | Expression;
 
 export type ProcessEntitiesOptions = {
   /**
@@ -63,7 +65,7 @@ export type ProcessEntitiesOptions = {
    * 
    * Defaults to `null`
    */
-  tagFilter?: ((tagName: string, jPathOrMatcher: string | Matcher) => boolean) | null;
+  tagFilter?: ((tagName: string, jPathOrMatcher: JPathOrMatcher) => boolean) | null;
 };
 
 export type X2jOptions = {
@@ -108,7 +110,7 @@ export type X2jOptions = {
    * 
    * Defaults to `true`
    */
-  ignoreAttributes?: boolean | (string | RegExp)[] | ((attrName: string, jPathOrMatcher: string | Matcher) => boolean);
+  ignoreAttributes?: boolean | (string | RegExp)[] | ((attrName: string, jPathOrMatcher: JPathOrMatcher) => boolean);
 
   /**
    * Whether to remove namespace string from tag and attribute names
@@ -175,7 +177,7 @@ export type X2jOptions = {
    * 
    * Defaults to `(tagName, val, jPathOrMatcher, hasAttributes, isLeafNode) => val`
    */
-  tagValueProcessor?: (tagName: string, tagValue: string, jPathOrMatcher: string | Matcher, hasAttributes: boolean, isLeafNode: boolean) => unknown;
+  tagValueProcessor?: (tagName: string, tagValue: string, jPathOrMatcher: JPathOrMatcher, hasAttributes: boolean, isLeafNode: boolean) => unknown;
 
   /**
    * Control how attribute value should be parsed
@@ -188,7 +190,7 @@ export type X2jOptions = {
    * 
    * Defaults to `(attrName, val, jPathOrMatcher) => val`
    */
-  attributeValueProcessor?: (attrName: string, attrValue: string, jPathOrMatcher: string | Matcher) => unknown;
+  attributeValueProcessor?: (attrName: string, attrValue: string, jPathOrMatcher: JPathOrMatcher) => unknown;
 
   /**
    * Options to pass to `strnum` for parsing numbers
@@ -206,7 +208,7 @@ export type X2jOptions = {
    * 
    * Defaults to `[]`
    */
-  stopNodes?: (string | Expression)[];
+  stopNodes?: JPathOrExpression[];
 
   /**
    * List of tags without closing tags
@@ -233,7 +235,7 @@ export type X2jOptions = {
    * 
    * Defaults to `() => false`
    */
-  isArray?: (tagName: string, jPathOrMatcher: string | Matcher, isLeafNode: boolean, isAttribute: boolean) => boolean;
+  isArray?: (tagName: string, jPathOrMatcher: JPathOrMatcher, isLeafNode: boolean, isAttribute: boolean) => boolean;
 
   /**
    * Whether to process default and DOCTYPE entities
@@ -295,7 +297,7 @@ export type X2jOptions = {
    * 
    * Defaults to `(tagName, jPathOrMatcher, attrs) => tagName`
    */
-  updateTag?: (tagName: string, jPathOrMatcher: string | Matcher, attrs: { [k: string]: string }) => string | boolean;
+  updateTag?: (tagName: string, jPathOrMatcher: JPathOrMatcher, attrs: { [k: string]: string }) => string | boolean;
 
   /**
    * If true, adds a Symbol to all object nodes, accessible by {@link XMLParser.getMetaDataSymbol} with
@@ -479,7 +481,7 @@ export type XmlBuilderOptions = {
    * 
    * Defaults to `[]`
    */
-  stopNodes?: (string | Expression)[];
+  stopNodes?: JPathOrExpression[];
 
   /**
    * Control how tag value should be parsed. Called only if tag value is not empty

package/src/pem.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Types copied from path-expression-matcher
+ * @version <version>
+ * @updated <date>
+ *
+ * Update this file when path-expression-matcher releases a new version.
+ * Source: https://github.com/NaturalIntelligence/path-expression-matcher
+ */
+
+/**
+ * Options for creating an Expression
+ */
+export interface ExpressionOptions {
+  /**
+   * Path separator character
+   * @default '.'
+   */
+  separator?: string;
+}
+
+/**
+ * Parsed segment from an expression pattern
+ */
+export interface Segment {
+  type: 'tag' | 'deep-wildcard';
+  tag?: string;
+  namespace?: string;
+  attrName?: string;
+  attrValue?: string;
+  position?: 'first' | 'last' | 'odd' | 'even' | 'nth';
+  positionValue?: number;
+}
+
+/**
+ * Expression - Parses and stores a tag pattern expression.
+ * Patterns are parsed once and stored in an optimized structure for fast matching.
+ * 
+ * @example
+ * ```typescript
+ * const expr = new Expression("root.users.user");
+ * const expr2 = new Expression("..user[id]:first");
+ * const expr3 = new Expression("root/users/user", { separator: '/' });
+ * ```
+ * 
+ * Pattern Syntax:
+ * - `root.users.user`      — Match exact path
+ * - `..user`               — Match "user" at any depth (deep wildcard)
+ * - `user[id]`             — Match user tag with "id" attribute
+ * - `user[id=123]`         — Match user tag where id="123"
+ * - `user:first`           — Match first occurrence of user tag
+ * - `ns::user`             — Match user tag with namespace "ns"
+ * - `ns::user[id]:first`   — Combine namespace, attribute, and position
+ */
+export class Expression {
+  readonly pattern: string;
+  readonly separator: string;
+  readonly segments: Segment[];
+
+  constructor(pattern: string, options?: ExpressionOptions);
+
+  get length(): number;
+  hasDeepWildcard(): boolean;
+  hasAttributeCondition(): boolean;
+  hasPositionSelector(): boolean;
+  toString(): string;
+}
+
+// ---------------------------------------------------------------------------
+// ReadonlyMatcher
+// ---------------------------------------------------------------------------
+
+/**
+ * A live read-only view of a {@link Matcher} instance, returned by {@link Matcher.readOnly}.
+ *
+ * All query and inspection methods work normally and always reflect the current
+ * state of the underlying matcher. State-mutating methods (`push`, `pop`,
+ * `reset`, `updateCurrent`, `restore`) are not present — calling them on the
+ * underlying Proxy throws a `TypeError` at runtime.
+ *
+ * This is the type received by all FXP user callbacks when `jPath: false`.
+ */
+export interface ReadonlyMatcher {
+  readonly separator: string;
+
+  /** Check if current path matches an Expression. */
+  matches(expression: Expression): boolean;
+
+  /** Get current tag name, or `undefined` if path is empty. */
+  getCurrentTag(): string | undefined;
+
+  /** Get current namespace, or `undefined` if not present. */
+  getCurrentNamespace(): string | undefined;
+
+  /** Get attribute value of the current node. */
+  getAttrValue(attrName: string): any;
+
+  /** Check if the current node has a given attribute. */
+  hasAttr(attrName: string): boolean;
+
+  /** Sibling position of the current node (child index in parent). */
+  getPosition(): number;
+
+  /** Occurrence counter of the current tag name at this level. */
+  getCounter(): number;
+
+  /** Number of nodes in the current path. */
+  getDepth(): number;
+
+  /** Current path as a string (e.g. `"root.users.user"`). */
+  toString(separator?: string, includeNamespace?: boolean): string;
+
+  /** Current path as an array of tag names. */
+  toArray(): string[];
+
+  /**
+   * Create a snapshot of the current state.
+   * The snapshot can be passed to the real {@link Matcher.restore} if needed.
+   */
+  snapshot(): MatcherSnapshot;
+}
+
+/** Internal node structure — exposed via snapshot only. */
+export interface PathNode {
+  tag: string;
+  namespace?: string;
+  position: number;
+  counter: number;
+  values?: Record<string, any>;
+}
+
+/** Snapshot of matcher state returned by `snapshot()` and `readOnly().snapshot()`. */
+export interface MatcherSnapshot {
+  path: PathNode[];
+  siblingStacks: Map<string, number>[];
+}

package/src/xmlparser/OrderedObjParser.js

@@ -113,6 +113,10 @@ export default class OrderedObjParser {
     // Initialize path matcher for path-expression-matcher
     this.matcher = new Matcher();
 
+    // Live read-only proxy of matcher — PEM creates and caches this internally.
+    // All user callbacks receive this instead of the mutable matcher.
+    this.readonlyMatcher = this.matcher.readOnly();
+
     // Flag to track if current node is a stop node (optimization)
     this.isCurrentNodeStopNode = false;
 
@@ -225,7 +229,7 @@ function buildAttributesMap(attrStr, jPath, tagName) {
         if (this.options.trimValues) {
           parsedVal = parsedVal.trim();
         }
-        parsedVal = this.replaceEntitiesValue(parsedVal, tagName, jPath);
+        parsedVal = this.replaceEntitiesValue(parsedVal, tagName, this.readonlyMatcher);
         rawAttrsForMatcher[attrName] = parsedVal;
       }
     }
@@ -240,7 +244,7 @@ function buildAttributesMap(attrStr, jPath, tagName) {
       const attrName = this.resolveNameSpace(matches[i][1]);
 
       // Convert jPath to string if needed for ignoreAttributesFn
-      const jPathStr = this.options.jPath ? jPath.toString() : jPath;
+      const jPathStr = this.options.jPath ? jPath.toString() : this.readonlyMatcher;
       if (this.ignoreAttributesFn(attrName, jPathStr)) {
         continue
       }
@@ -259,10 +263,10 @@ function buildAttributesMap(attrStr, jPath, tagName) {
           if (this.options.trimValues) {
             oldVal = oldVal.trim();
           }
-          oldVal = this.replaceEntitiesValue(oldVal, tagName, jPath);
+          oldVal = this.replaceEntitiesValue(oldVal, tagName, this.readonlyMatcher);
 
-          // Pass jPath string or matcher based on options.jPath setting
-          const jPathOrMatcher = this.options.jPath ? jPath.toString() : jPath;
+          // Pass jPath string or readonlyMatcher based on options.jPath setting
+          const jPathOrMatcher = this.options.jPath ? jPath.toString() : this.readonlyMatcher;
           const newVal = this.options.attributeValueProcessor(attrName, oldVal, jPathOrMatcher);
           if (newVal === null || newVal === undefined) {
             //don't parse
@@ -329,7 +333,7 @@ const parseXml = function (xmlData) {
         tagName = transformTagName(this.options.transformTagName, tagName, "", this.options).tagName;
 
         if (currentNode) {
-          textData = this.saveTextToParentTag(textData, currentNode, this.matcher);
+          textData = this.saveTextToParentTag(textData, currentNode, this.readonlyMatcher);
         }
 
         //check if last tag of nested tag was unpaired tag
@@ -354,7 +358,7 @@ const parseXml = function (xmlData) {
         let tagData = readTagExp(xmlData, i, false, "?>");
         if (!tagData) throw new Error("Pi Tag is not closed.");
 
-        textData = this.saveTextToParentTag(textData, currentNode, this.matcher);
+        textData = this.saveTextToParentTag(textData, currentNode, this.readonlyMatcher);
         if ((this.options.ignoreDeclaration && tagData.tagName === "?xml") || this.options.ignorePiTags) {
           //do nothing
         } else {
@@ -365,7 +369,7 @@ const parseXml = function (xmlData) {
           if (tagData.tagName !== tagData.tagExp && tagData.attrExpPresent) {
             childNode[":@"] = this.buildAttributesMap(tagData.tagExp, this.matcher, tagData.tagName);
           }
-          this.addChild(currentNode, childNode, this.matcher, i);
+          this.addChild(currentNode, childNode, this.readonlyMatcher, i);
         }
 
 
@@ -375,7 +379,7 @@ const parseXml = function (xmlData) {
         if (this.options.commentPropName) {
           const comment = xmlData.substring(i + 4, endIndex - 2);
 
-          textData = this.saveTextToParentTag(textData, currentNode, this.matcher);
+          textData = this.saveTextToParentTag(textData, currentNode, this.readonlyMatcher);
 
           currentNode.add(this.options.commentPropName, [{ [this.options.textNodeName]: comment }]);
         }
@@ -388,9 +392,9 @@ const parseXml = function (xmlData) {
         const closeIndex = findClosingIndex(xmlData, "]]>", i, "CDATA is not closed.") - 2;
         const tagExp = xmlData.substring(i + 9, closeIndex);
 
-        textData = this.saveTextToParentTag(textData, currentNode, this.matcher);
+        textData = this.saveTextToParentTag(textData, currentNode, this.readonlyMatcher);
 
-        let val = this.parseTextData(tagExp, currentNode.tagname, this.matcher, true, false, true, true);
+        let val = this.parseTextData(tagExp, currentNode.tagname, this.readonlyMatcher, true, false, true, true);
         if (val == undefined) val = "";
 
         //cdata should be set even if it is 0 length string
@@ -432,7 +436,7 @@ const parseXml = function (xmlData) {
         if (currentNode && textData) {
           if (currentNode.tagname !== '!xml') {
             //when nested tag is found
-            textData = this.saveTextToParentTag(textData, currentNode, this.matcher, false);
+            textData = this.saveTextToParentTag(textData, currentNode, this.readonlyMatcher, false);
           }
         }
 
@@ -522,7 +526,7 @@ const parseXml = function (xmlData) {
           this.matcher.pop(); // Pop the stop node tag
           this.isCurrentNodeStopNode = false; // Reset flag
 
-          this.addChild(currentNode, childNode, this.matcher, startIndex);
+          this.addChild(currentNode, childNode, this.readonlyMatcher, startIndex);
         } else {
           //selfClosing tag
           if (isSelfClosing) {
@@ -532,7 +536,7 @@ const parseXml = function (xmlData) {
             if (prefixedAttrs) {
               childNode[":@"] = prefixedAttrs;
             }
-            this.addChild(currentNode, childNode, this.matcher, startIndex);
+            this.addChild(currentNode, childNode, this.readonlyMatcher, startIndex);
             this.matcher.pop(); // Pop self-closing tag
             this.isCurrentNodeStopNode = false; // Reset flag
           }
@@ -541,7 +545,7 @@ const parseXml = function (xmlData) {
             if (prefixedAttrs) {
               childNode[":@"] = prefixedAttrs;
             }
-            this.addChild(currentNode, childNode, this.matcher, startIndex);
+            this.addChild(currentNode, childNode, this.readonlyMatcher, startIndex);
             this.matcher.pop(); // Pop unpaired tag
             this.isCurrentNodeStopNode = false; // Reset flag
             i = result.closeIndex;
@@ -559,7 +563,7 @@ const parseXml = function (xmlData) {
             if (prefixedAttrs) {
               childNode[":@"] = prefixedAttrs;
             }
-            this.addChild(currentNode, childNode, this.matcher, startIndex);
+            this.addChild(currentNode, childNode, this.readonlyMatcher, startIndex);
             currentNode = childNode;
           }
           textData = "";

package/src/xmlparser/XMLParser.js

@@ -35,7 +35,7 @@ export default class XMLParser {
         orderedObjParser.addExternalEntities(this.externalEntities);
         const orderedResult = orderedObjParser.parseXml(xmlData);
         if (this.options.preserveOrder || orderedResult === undefined) return orderedResult;
-        else return prettify(orderedResult, this.options, orderedObjParser.matcher);
+        else return prettify(orderedResult, this.options, orderedObjParser.matcher, orderedObjParser.readonlyMatcher);
     }
 
     /**
@@ -68,4 +68,4 @@ export default class XMLParser {
     static getMetaDataSymbol() {
         return XmlNode.getMetaDataSymbol();
     }
-}
+}

package/src/xmlparser/node2json.js

@@ -35,18 +35,17 @@ function stripAttributePrefix(attrs, prefix) {
  * @param {Matcher} matcher - Path matcher instance
  * @returns 
  */
-export default function prettify(node, options, matcher) {
-  return compress(node, options, matcher);
+export default function prettify(node, options, matcher, readonlyMatcher) {
+  return compress(node, options, matcher, readonlyMatcher);
 }
 
 /**
- * 
  * @param {array} arr 
  * @param {object} options 
  * @param {Matcher} matcher - Path matcher instance
  * @returns object
  */
-function compress(arr, options, matcher) {
+function compress(arr, options, matcher, readonlyMatcher) {
   let text;
   const compressedObj = {}; //This is intended to be a plain object
   for (let i = 0; i < arr.length; i++) {
@@ -69,11 +68,11 @@ function compress(arr, options, matcher) {
       continue;
     } else if (tagObj[property]) {
 
-      let val = compress(tagObj[property], options, matcher);
+      let val = compress(tagObj[property], options, matcher, readonlyMatcher);
       const isLeaf = isLeafTag(val, options);
 
       if (tagObj[":@"]) {
-        assignAttributes(val, tagObj[":@"], matcher, options);
+        assignAttributes(val, tagObj[":@"], readonlyMatcher, options);
       } else if (Object.keys(val).length === 1 && val[options.textNodeName] !== undefined && !options.alwaysCreateTextNode) {
         val = val[options.textNodeName];
       } else if (Object.keys(val).length === 0) {
@@ -95,8 +94,8 @@ function compress(arr, options, matcher) {
         //TODO: if a node is not an array, then check if it should be an array
         //also determine if it is a leaf node
 
-        // Pass jPath string or matcher based on options.jPath setting
-        const jPathOrMatcher = options.jPath ? matcher.toString() : matcher;
+        // Pass jPath string or readonlyMatcher based on options.jPath setting
+        const jPathOrMatcher = options.jPath ? readonlyMatcher.toString() : readonlyMatcher;
         if (options.isArray(property, jPathOrMatcher, isLeaf)) {
           compressedObj[property] = [val];
         } else {
@@ -128,7 +127,7 @@ function propName(obj) {
   }
 }
 
-function assignAttributes(obj, attrMap, matcher, options) {
+function assignAttributes(obj, attrMap, readonlyMatcher, options) {
   if (attrMap) {
     const keys = Object.keys(attrMap);
     const len = keys.length; //don't make it inline
@@ -143,8 +142,8 @@ function assignAttributes(obj, attrMap, matcher, options) {
       // For attributes, we need to create a temporary path
       // Pass jPath string or matcher based on options.jPath setting
       const jPathOrMatcher = options.jPath
-        ? matcher.toString() + "." + rawAttrName
-        : matcher;
+        ? readonlyMatcher.toString() + "." + rawAttrName
+        : readonlyMatcher;
 
       if (options.isArray(atrrName, jPathOrMatcher, true, true)) {
         obj[atrrName] = [attrMap[atrrName]];