path-expression-matcher 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,531 @@
+# path-expression-matcher
+
+Efficient path tracking and pattern matching for XML, JSON, YAML or any other parsers.
+
+## 🎯 Purpose
+
+`path-expression-matcher` provides two core classes for tracking and matching paths:
+
+- **`Expression`**: Parses and stores pattern expressions (e.g., `"root.users.user[id]"`)
+- **`Matcher`**: Tracks current path during parsing and matches against expressions
+
+Compatible with [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser) and similar tools.
+
+## 📦 Installation
+
+```bash
+npm install path-expression-matcher
+```
+
+## 🚀 Quick Start
+
+```javascript
+import { Expression, Matcher } from 'path-expression-matcher';
+
+// Create expression (parse once, reuse many times)
+const expr = new Expression("root.users.user");
+
+// Create matcher (tracks current path)
+const matcher = new Matcher();
+
+matcher.push("root");
+matcher.push("users");
+matcher.push("user", { id: "123" });
+
+// Match current path against expression
+if (matcher.matches(expr)) {
+  console.log("Match found!");
+  console.log("Current path:", matcher.toString()); // "root.users.user"
+}
+```
+
+## 📖 Pattern Syntax
+
+### Basic Paths
+
+```javascript
+"root.users.user"           // Exact path match
+"*.users.user"              // Wildcard: any parent
+"root.*.user"               // Wildcard: any middle
+"root.users.*"              // Wildcard: any child
+```
+
+### Deep Wildcard
+
+```javascript
+"..user"                    // user anywhere in tree
+"root..user"                // user anywhere under root
+"..users..user"             // users somewhere, then user below it
+```
+
+### Attribute Matching
+
+```javascript
+"user[id]"                  // user with "id" attribute
+"user[type=admin]"          // user with type="admin" (current node only)
+"root[lang]..user"          // user under root that has "lang" attribute
+```
+
+### Position Selectors
+
+```javascript
+"user:first"                // First user (counter=0)
+"user:nth(2)"               // Third user (counter=2, zero-based)
+"user:odd"                  // Odd-numbered users (counter=1,3,5...)
+"user:even"                 // Even-numbered users (counter=0,2,4...)
+"root.users.user:first"     // First user under users
+```
+
+**Note:** Position selectors use the **counter** (occurrence count of the tag name), not the position (child index). For example, in `<root><a/><b/><a/></root>`, the second `<a/>` has position=2 but counter=1.
+
+### Combined Patterns
+
+```javascript
+"..user[id]:first"          // First user with id, anywhere
+"root..user[type=admin]"    // Admin user under root
+```
+
+## 🔧 API Reference
+
+### Expression
+
+#### Constructor
+
+```javascript
+new Expression(pattern, options)
+```
+
+**Parameters:**
+- `pattern` (string): Pattern to parse
+- `options.separator` (string): Path separator (default: `'.'`)
+
+**Example:**
+```javascript
+const expr1 = new Expression("root.users.user");
+const expr2 = new Expression("root/users/user", { separator: '/' });
+```
+
+#### Methods
+
+- `hasDeepWildcard()` → boolean
+- `hasAttributeCondition()` → boolean
+- `hasPositionSelector()` → boolean
+- `toString()` → string
+
+### Matcher
+
+#### Constructor
+
+```javascript
+new Matcher(options)
+```
+
+**Parameters:**
+- `options.separator` (string): Default path separator (default: `'.'`)
+
+#### Path Tracking Methods
+
+##### `push(tagName, attrValues)`
+
+Add a tag to the current path. Position and counter are automatically calculated.
+
+**Parameters:**
+- `tagName` (string): Tag name
+- `attrValues` (object, optional): Attribute key-value pairs (current node only)
+
+**Example:**
+```javascript
+matcher.push("user", { id: "123", type: "admin" });
+matcher.push("item");  // No attributes
+```
+
+**Position vs Counter:**
+- **Position**: The child index in the parent (0, 1, 2, 3...)
+- **Counter**: How many times this tag name appeared at this level (0, 1, 2...)
+
+Example:
+```xml
+<root>
+  <a/>      <!-- position=0, counter=0 -->
+  <b/>      <!-- position=1, counter=0 -->
+  <a/>      <!-- position=2, counter=1 -->
+</root>
+```
+
+##### `pop()`
+
+Remove the last tag from the path.
+
+```javascript
+matcher.pop();
+```
+
+##### `updateCurrent(attrValues)`
+
+Update current node's attributes (useful when attributes are parsed after push).
+
+```javascript
+matcher.push("user");  // Don't know values yet
+// ... parse attributes ...
+matcher.updateCurrent({ id: "123" });
+```
+
+##### `reset()`
+
+Clear the entire path.
+
+```javascript
+matcher.reset();
+```
+
+#### Query Methods
+
+##### `matches(expression)`
+
+Check if current path matches an Expression.
+
+```javascript
+const expr = new Expression("root.users.user");
+if (matcher.matches(expr)) {
+  // Current path matches
+}
+```
+
+##### `getCurrentTag()`
+
+Get current tag name.
+
+```javascript
+const tag = matcher.getCurrentTag(); // "user"
+```
+
+##### `getAttrValue(attrName)`
+
+Get attribute value of current node.
+
+```javascript
+const id = matcher.getAttrValue("id"); // "123"
+```
+
+##### `hasAttr(attrName)`
+
+Check if current node has an attribute.
+
+```javascript
+if (matcher.hasAttr("id")) {
+  // Current node has "id" attribute
+}
+```
+
+##### `getPosition()`
+
+Get sibling position of current node (child index in parent).
+
+```javascript
+const position = matcher.getPosition(); // 0, 1, 2, ...
+```
+
+##### `getCounter()`
+
+Get repeat counter of current node (occurrence count of this tag name).
+
+```javascript
+const counter = matcher.getCounter(); // 0, 1, 2, ...
+```
+
+##### `getIndex()` (deprecated)
+
+Alias for `getPosition()`. Use `getPosition()` or `getCounter()` instead for clarity.
+
+```javascript
+const index = matcher.getIndex(); // Same as getPosition()
+```
+
+##### `getDepth()`
+
+Get current path depth.
+
+```javascript
+const depth = matcher.getDepth(); // 3 for "root.users.user"
+```
+
+##### `toString(separator?)`
+
+Get path as string.
+
+```javascript
+const path = matcher.toString();     // "root.users.user"
+const path2 = matcher.toString('/'); // "root/users/user"
+```
+
+##### `toArray()`
+
+Get path as array.
+
+```javascript
+const arr = matcher.toArray(); // ["root", "users", "user"]
+```
+
+#### State Management
+
+##### `snapshot()`
+
+Create a snapshot of current state.
+
+```javascript
+const snapshot = matcher.snapshot();
+```
+
+##### `restore(snapshot)`
+
+Restore from a snapshot.
+
+```javascript
+matcher.restore(snapshot);
+```
+
+## 💡 Usage Examples
+
+### Example 1: XML Parser with stopNodes
+
+```javascript
+import { XMLParser } from 'fast-xml-parser';
+import { Expression, Matcher } from 'path-expression-matcher';
+
+class MyParser {
+  constructor() {
+    this.matcher = new Matcher();
+    
+    // Pre-compile stop node patterns
+    this.stopNodeExpressions = [
+      new Expression("html.body.script"),
+      new Expression("html.body.style"),
+      new Expression("..svg"),
+    ];
+  }
+  
+  parseTag(tagName, attrs) {
+    this.matcher.push(tagName, attrs);
+    
+    // Check if this is a stop node
+    for (const expr of this.stopNodeExpressions) {
+      if (this.matcher.matches(expr)) {
+        // Don't parse children, read as raw text
+        return this.readRawContent();
+      }
+    }
+    
+    // Continue normal parsing
+    this.parseChildren();
+    
+    this.matcher.pop();
+  }
+}
+```
+
+### Example 2: Conditional Processing
+
+```javascript
+const matcher = new Matcher();
+const userExpr = new Expression("..user[type=admin]");
+const firstItemExpr = new Expression("..item:first");
+
+function processTag(tagName, value, attrs) {
+  matcher.push(tagName, attrs);
+  
+  if (matcher.matches(userExpr)) {
+    value = enhanceAdminUser(value);
+  }
+  
+  if (matcher.matches(firstItemExpr)) {
+    value = markAsFirst(value);
+  }
+  
+  matcher.pop();
+  return value;
+}
+```
+
+### Example 3: Path-based Filtering
+
+```javascript
+const patterns = [
+  new Expression("data.users.user"),
+  new Expression("data.posts.post"),
+  new Expression("..comment[approved=true]"),
+];
+
+function shouldInclude(matcher) {
+  return patterns.some(expr => matcher.matches(expr));
+}
+```
+
+### Example 4: Custom Separator
+
+```javascript
+const matcher = new Matcher({ separator: '/' });
+const expr = new Expression("root/config/database", { separator: '/' });
+
+matcher.push("root");
+matcher.push("config");
+matcher.push("database");
+
+console.log(matcher.toString()); // "root/config/database"
+console.log(matcher.matches(expr)); // true
+```
+
+### Example 5: Attribute Checking
+
+```javascript
+const matcher = new Matcher();
+matcher.push("root");
+matcher.push("user", { id: "123", type: "admin", status: "active" });
+
+// Check attribute existence (current node only)
+console.log(matcher.hasAttr("id"));        // true
+console.log(matcher.hasAttr("email"));     // false
+
+// Get attribute value (current node only)
+console.log(matcher.getAttrValue("type")); // "admin"
+
+// Match by attribute
+const expr1 = new Expression("user[id]");
+console.log(matcher.matches(expr1));       // true
+
+const expr2 = new Expression("user[type=admin]");
+console.log(matcher.matches(expr2));       // true
+```
+
+### Example 6: Position vs Counter
+
+```javascript
+const matcher = new Matcher();
+matcher.push("root");
+
+// Mixed tags at same level
+matcher.push("item");  // position=0, counter=0 (first item)
+matcher.pop();
+
+matcher.push("div");   // position=1, counter=0 (first div)
+matcher.pop();
+
+matcher.push("item");  // position=2, counter=1 (second item)
+
+console.log(matcher.getPosition()); // 2 (third child overall)
+console.log(matcher.getCounter());  // 1 (second "item" specifically)
+
+// :first uses counter, not position
+const expr = new Expression("root.item:first");
+console.log(matcher.matches(expr)); // false (counter=1, not 0)
+```
+
+## 🏗️ Architecture
+
+### Data Storage Strategy
+
+**Ancestor nodes:** Store only tag name, position, and counter (minimal memory)
+**Current node:** Store tag name, position, counter, and attribute values
+
+This design minimizes memory usage:
+- No attribute names stored (derived from values object when needed)
+- Attribute values only for current node, not ancestors
+- Attribute checking for ancestors is not supported (acceptable trade-off)
+- For 1M nodes with 3 attributes each, saves ~50MB vs storing attribute names
+
+### Matching Strategy
+
+Matching is performed **bottom-to-top** (from current node toward root):
+1. Start at current node
+2. Match segments from pattern end to start
+3. Attribute checking only works for current node (ancestors have no attribute data)
+4. Position selectors use **counter** (occurrence count), not position (child index)
+
+### Performance
+
+- **Expression parsing:** One-time cost when Expression is created
+- **Expression analysis:** Cached (hasDeepWildcard, hasAttributeCondition, hasPositionSelector)
+- **Path tracking:** O(1) for push/pop operations
+- **Pattern matching:** O(n*m) where n = path depth, m = pattern segments
+- **Memory per ancestor node:** ~40-60 bytes (tag, position, counter only)
+- **Memory per current node:** ~80-120 bytes (adds attribute values)
+
+## 🎓 Design Patterns
+
+### Pre-compile Patterns (Recommended)
+
+```javascript
+// ✅ GOOD: Parse once, reuse many times
+const expr = new Expression("..user[id]");
+
+for (let i = 0; i < 1000; i++) {
+  if (matcher.matches(expr)) {
+    // ...
+  }
+}
+```
+
+```javascript
+// ❌ BAD: Parse on every iteration
+for (let i = 0; i < 1000; i++) {
+  if (matcher.matches(new Expression("..user[id]"))) {
+    // ...
+  }
+}
+```
+
+### Batch Pattern Checking
+
+```javascript
+// For multiple patterns, check all at once
+const patterns = [
+  new Expression("..user"),
+  new Expression("..post"),
+  new Expression("..comment"),
+];
+
+function matchesAny(matcher, patterns) {
+  return patterns.some(expr => matcher.matches(expr));
+}
+```
+
+## 🔗 Integration with fast-xml-parser
+
+**Basic integration:**
+
+```javascript
+import { XMLParser } from 'fast-xml-parser';
+import { Expression, Matcher } from 'path-expression-matcher';
+
+const parser = new XMLParser({
+  // Custom options using path-expression-matcher
+  stopNodes: ["script", "style"].map(tag => new Expression(`..${tag}`)),
+  
+  tagValueProcessor: (tagName, value, jPath, hasAttrs, isLeaf, matcher) => {
+    // matcher is available in callbacks
+    if (matcher.matches(new Expression("..user[type=admin]"))) {
+      return enhanceValue(value);
+    }
+    return value;
+  }
+});
+```
+
+## 🧪 Testing
+
+```bash
+npm test
+```
+
+All 77 tests covering:
+- Pattern parsing (exact, wildcards, attributes, position)
+- Path tracking (push, pop, update)
+- Pattern matching (all combinations)
+- Edge cases and error conditions
+
+## 📄 License
+
+MIT
+
+## 🤝 Contributing
+
+Issues and PRs welcome! This package is designed to be used by XML/JSON parsers like fast-xml-parser.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "path-expression-matcher",
+  "version": "1.0.0",
+  "description": "Efficient path tracking and pattern matching for XML/JSON parsers",
+  "main": "src/index.js",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./Expression": "./src/Expression.js",
+    "./Matcher": "./src/Matcher.js"
+  },
+  "scripts": {
+    "test": "node test/test.js"
+  },
+  "keywords": [
+    "xml",
+    "json",
+    "yaml",
+    "path",
+    "matcher",
+    "pattern",
+    "xpath",
+    "selector",
+    "parser",
+    "fast-xml-parser",
+    "fast-xml-builder"
+  ],
+  "author": "Amit Gupta (https://solothought.com)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NaturalIntelligence/path-expression-matcher"
+  },
+  "bugs": {
+    "url": "https://github.com/NaturalIntelligence/path-expression-matcher/issues"
+  },
+  "homepage": "https://github.com/NaturalIntelligence/path-expression-matcher#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/NaturalIntelligence"
+    }
+  ]
+}

package/src/Expression.js

@@ -0,0 +1,169 @@
+/**
+ * Expression - Parses and stores a tag pattern expression
+ * 
+ * Patterns are parsed once and stored in an optimized structure for fast matching.
+ * 
+ * @example
+ * const expr = new Expression("root.users.user");
+ * const expr2 = new Expression("..user[id]:first");
+ * const expr3 = new Expression("root/users/user", { separator: '/' });
+ */
+export default class Expression {
+  /**
+   * Create a new Expression
+   * @param {string} pattern - Pattern string (e.g., "root.users.user", "..user[id]")
+   * @param {Object} options - Configuration options
+   * @param {string} options.separator - Path separator (default: '.')
+   */
+  constructor(pattern, options = {}) {
+    this.pattern = pattern;
+    this.separator = options.separator || '.';
+    this.segments = this._parse(pattern);
+
+    // Cache expensive checks for performance (O(1) instead of O(n))
+    this._hasDeepWildcard = this.segments.some(seg => seg.type === 'deep-wildcard');
+    this._hasAttributeCondition = this.segments.some(seg => seg.attrName !== undefined);
+    this._hasPositionSelector = this.segments.some(seg => seg.position !== undefined);
+  }
+
+  /**
+   * Parse pattern string into segments
+   * @private
+   * @param {string} pattern - Pattern to parse
+   * @returns {Array} Array of segment objects
+   */
+  _parse(pattern) {
+    const segments = [];
+
+    // Split by separator but handle ".." specially
+    let i = 0;
+    let currentPart = '';
+
+    while (i < pattern.length) {
+      if (pattern[i] === this.separator) {
+        // Check if next char is also separator (deep wildcard)
+        if (i + 1 < pattern.length && pattern[i + 1] === this.separator) {
+          // Flush current part if any
+          if (currentPart.trim()) {
+            segments.push(this._parseSegment(currentPart.trim()));
+            currentPart = '';
+          }
+          // Add deep wildcard
+          segments.push({ type: 'deep-wildcard' });
+          i += 2; // Skip both separators
+        } else {
+          // Regular separator
+          if (currentPart.trim()) {
+            segments.push(this._parseSegment(currentPart.trim()));
+          }
+          currentPart = '';
+          i++;
+        }
+      } else {
+        currentPart += pattern[i];
+        i++;
+      }
+    }
+
+    // Flush remaining part
+    if (currentPart.trim()) {
+      segments.push(this._parseSegment(currentPart.trim()));
+    }
+
+    return segments;
+  }
+
+  /**
+   * Parse a single segment
+   * @private
+   * @param {string} part - Segment string (e.g., "user", "user[id]", "user:first")
+   * @returns {Object} Segment object
+   */
+  _parseSegment(part) {
+    const segment = { type: 'tag' };
+
+    // Match pattern: tagname[attr] or tagname[attr=value] or tagname:position
+    // Examples: user, user[id], user[type=admin], user:first, user[id]:first, user:nth(2)
+    const match = part.match(/^([^[\]:]+)(?:\[([^\]]+)\])?(?::(\w+(?:\(\d+\))?))?$/);
+
+    if (!match) {
+      throw new Error(`Invalid segment pattern: ${part}`);
+    }
+
+    segment.tag = match[1].trim();
+
+    // Parse attribute condition [attr] or [attr=value]
+    if (match[2]) {
+      const attrExpr = match[2];
+
+      if (attrExpr.includes('=')) {
+        const eqIndex = attrExpr.indexOf('=');
+        const attrName = attrExpr.substring(0, eqIndex).trim();
+        const attrValue = attrExpr.substring(eqIndex + 1).trim();
+
+        segment.attrName = attrName;
+        segment.attrValue = attrValue;
+      } else {
+        segment.attrName = attrExpr.trim();
+      }
+    }
+
+    // Parse position selector :first, :nth(n), :odd, :even
+    if (match[3]) {
+      const posExpr = match[3];
+
+      // Check for :nth(n) pattern
+      const nthMatch = posExpr.match(/^nth\((\d+)\)$/);
+      if (nthMatch) {
+        segment.position = 'nth';
+        segment.positionValue = parseInt(nthMatch[1], 10);
+      } else if (['first', 'odd', 'even'].includes(posExpr)) {
+        segment.position = posExpr;
+      } else {
+        throw new Error(`Invalid position selector: :${posExpr}`);
+      }
+    }
+
+    return segment;
+  }
+
+  /**
+   * Get the number of segments
+   * @returns {number}
+   */
+  get length() {
+    return this.segments.length;
+  }
+
+  /**
+   * Check if expression contains deep wildcard
+   * @returns {boolean}
+   */
+  hasDeepWildcard() {
+    return this._hasDeepWildcard;
+  }
+
+  /**
+   * Check if expression has attribute conditions
+   * @returns {boolean}
+   */
+  hasAttributeCondition() {
+    return this._hasAttributeCondition;
+  }
+
+  /**
+   * Check if expression has position selectors
+   * @returns {boolean}
+   */
+  hasPositionSelector() {
+    return this._hasPositionSelector;
+  }
+
+  /**
+   * Get string representation
+   * @returns {string}
+   */
+  toString() {
+    return this.pattern;
+  }
+}

package/src/Matcher.js

@@ -0,0 +1,380 @@
+/**
+ * Matcher - Tracks current path in XML/JSON tree and matches against Expressions
+ * 
+ * The matcher maintains a stack of nodes representing the current path from root to
+ * current tag. It only stores attribute values for the current (top) node to minimize
+ * memory usage. Sibling tracking is used to auto-calculate position and counter.
+ * 
+ * @example
+ * const matcher = new Matcher();
+ * matcher.push("root", {});
+ * matcher.push("users", {});
+ * matcher.push("user", { id: "123", type: "admin" });
+ * 
+ * const expr = new Expression("root.users.user");
+ * matcher.matches(expr); // true
+ */
+export default class Matcher {
+  /**
+   * Create a new Matcher
+   * @param {Object} options - Configuration options
+   * @param {string} options.separator - Default path separator (default: '.')
+   */
+  constructor(options = {}) {
+    this.separator = options.separator || '.';
+    this.path = [];
+    this.siblingStacks = [];
+    // Each path node: { tag: string, values: object, position: number, counter: number }
+    // values only present for current (last) node
+    // Each siblingStacks entry: Map<tagName, count> tracking occurrences at each level
+  }
+
+  /**
+   * Push a new tag onto the path
+   * @param {string} tagName - Name of the tag
+   * @param {Object} attrValues - Attribute key-value pairs for current node (optional)
+   */
+  push(tagName, attrValues = null) {
+    // Remove values from previous current node (now becoming ancestor)
+    if (this.path.length > 0) {
+      const prev = this.path[this.path.length - 1];
+      prev.values = undefined;
+    }
+
+    // Get or create sibling tracking for current level
+    const currentLevel = this.path.length;
+    if (!this.siblingStacks[currentLevel]) {
+      this.siblingStacks[currentLevel] = new Map();
+    }
+
+    const siblings = this.siblingStacks[currentLevel];
+
+    // Calculate counter (how many times this tag appeared at this level)
+    const counter = siblings.get(tagName) || 0;
+
+    // Calculate position (total children at this level so far)
+    let position = 0;
+    for (const count of siblings.values()) {
+      position += count;
+    }
+
+    // Update sibling count for this tag
+    siblings.set(tagName, counter + 1);
+
+    // Create new node
+    const node = {
+      tag: tagName,
+      position: position,
+      counter: counter
+    };
+
+    // Store values only for current node
+    if (attrValues !== null && attrValues !== undefined) {
+      node.values = attrValues;
+    }
+
+    this.path.push(node);
+  }
+
+  /**
+   * Pop the last tag from the path
+   * @returns {Object|undefined} The popped node
+   */
+  pop() {
+    if (this.path.length === 0) {
+      return undefined;
+    }
+
+    const node = this.path.pop();
+
+    // Clean up sibling tracking for this level
+    if (this.siblingStacks[this.path.length]) {
+      delete this.siblingStacks[this.path.length];
+    }
+
+    return node;
+  }
+
+  /**
+   * Update current node's attribute values
+   * Useful when attributes are parsed after push
+   * @param {Object} attrValues - Attribute values
+   */
+  updateCurrent(attrValues) {
+    if (this.path.length > 0) {
+      const current = this.path[this.path.length - 1];
+      if (attrValues !== null && attrValues !== undefined) {
+        current.values = attrValues;
+      }
+    }
+  }
+
+  /**
+   * Get current tag name
+   * @returns {string|undefined}
+   */
+  getCurrentTag() {
+    return this.path.length > 0 ? this.path[this.path.length - 1].tag : undefined;
+  }
+
+  /**
+   * Get current node's attribute value
+   * @param {string} attrName - Attribute name
+   * @returns {*} Attribute value or undefined
+   */
+  getAttrValue(attrName) {
+    if (this.path.length === 0) return undefined;
+    const current = this.path[this.path.length - 1];
+    return current.values?.[attrName];
+  }
+
+  /**
+   * Check if current node has an attribute
+   * @param {string} attrName - Attribute name
+   * @returns {boolean}
+   */
+  hasAttr(attrName) {
+    if (this.path.length === 0) return false;
+    const current = this.path[this.path.length - 1];
+    return current.values !== undefined && attrName in current.values;
+  }
+
+  /**
+   * Get current node's sibling position (child index in parent)
+   * @returns {number}
+   */
+  getPosition() {
+    if (this.path.length === 0) return -1;
+    return this.path[this.path.length - 1].position ?? 0;
+  }
+
+  /**
+   * Get current node's repeat counter (occurrence count of this tag name)
+   * @returns {number}
+   */
+  getCounter() {
+    if (this.path.length === 0) return -1;
+    return this.path[this.path.length - 1].counter ?? 0;
+  }
+
+  /**
+   * Get current node's sibling index (alias for getPosition for backward compatibility)
+   * @returns {number}
+   * @deprecated Use getPosition() or getCounter() instead
+   */
+  getIndex() {
+    return this.getPosition();
+  }
+
+  /**
+   * Get current path depth
+   * @returns {number}
+   */
+  getDepth() {
+    return this.path.length;
+  }
+
+  /**
+   * Get path as string
+   * @param {string} separator - Optional separator (uses default if not provided)
+   * @returns {string}
+   */
+  toString(separator) {
+    const sep = separator || this.separator;
+    return this.path.map(n => n.tag).join(sep);
+  }
+
+  /**
+   * Get path as array of tag names
+   * @returns {string[]}
+   */
+  toArray() {
+    return this.path.map(n => n.tag);
+  }
+
+  /**
+   * Reset the path to empty
+   */
+  reset() {
+    this.path = [];
+    this.siblingStacks = [];
+  }
+
+  /**
+   * Match current path against an Expression
+   * @param {Expression} expression - The expression to match against
+   * @returns {boolean} True if current path matches the expression
+   */
+  matches(expression) {
+    const segments = expression.segments;
+
+    if (segments.length === 0) {
+      return false;
+    }
+
+    // Handle deep wildcard patterns
+    if (expression.hasDeepWildcard()) {
+      return this._matchWithDeepWildcard(segments);
+    }
+
+    // Simple path matching (no deep wildcards)
+    return this._matchSimple(segments);
+  }
+
+  /**
+   * Match simple path (no deep wildcards)
+   * @private
+   */
+  _matchSimple(segments) {
+    // Path must be same length as segments
+    if (this.path.length !== segments.length) {
+      return false;
+    }
+
+    // Match each segment bottom-to-top
+    for (let i = 0; i < segments.length; i++) {
+      const segment = segments[i];
+      const node = this.path[i];
+      const isCurrentNode = (i === this.path.length - 1);
+
+      if (!this._matchSegment(segment, node, isCurrentNode)) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Match path with deep wildcards
+   * @private
+   */
+  _matchWithDeepWildcard(segments) {
+    let pathIdx = this.path.length - 1;  // Start from current node (bottom)
+    let segIdx = segments.length - 1;     // Start from last segment
+
+    while (segIdx >= 0 && pathIdx >= 0) {
+      const segment = segments[segIdx];
+
+      if (segment.type === 'deep-wildcard') {
+        // ".." matches zero or more levels
+        segIdx--;
+
+        if (segIdx < 0) {
+          // Pattern ends with "..", always matches
+          return true;
+        }
+
+        // Find where next segment matches in the path
+        const nextSeg = segments[segIdx];
+        let found = false;
+
+        for (let i = pathIdx; i >= 0; i--) {
+          const isCurrentNode = (i === this.path.length - 1);
+          if (this._matchSegment(nextSeg, this.path[i], isCurrentNode)) {
+            pathIdx = i - 1;
+            segIdx--;
+            found = true;
+            break;
+          }
+        }
+
+        if (!found) {
+          return false;
+        }
+      } else {
+        // Regular segment
+        const isCurrentNode = (pathIdx === this.path.length - 1);
+        if (!this._matchSegment(segment, this.path[pathIdx], isCurrentNode)) {
+          return false;
+        }
+        pathIdx--;
+        segIdx--;
+      }
+    }
+
+    // All segments must be consumed
+    return segIdx < 0;
+  }
+
+  /**
+   * Match a single segment against a node
+   * @private
+   * @param {Object} segment - Segment from Expression
+   * @param {Object} node - Node from path
+   * @param {boolean} isCurrentNode - Whether this is the current (last) node
+   * @returns {boolean}
+   */
+  _matchSegment(segment, node, isCurrentNode) {
+    // Match tag name (* is wildcard)
+    if (segment.tag !== '*' && segment.tag !== node.tag) {
+      return false;
+    }
+
+    // Match attribute name (check if node has this attribute)
+    // Can only check for current node since ancestors don't have values
+    if (segment.attrName !== undefined) {
+      if (!isCurrentNode) {
+        // Can't check attributes for ancestor nodes (values not stored)
+        return false;
+      }
+
+      if (!node.values || !(segment.attrName in node.values)) {
+        return false;
+      }
+
+      // Match attribute value (only possible for current node)
+      if (segment.attrValue !== undefined) {
+        const actualValue = node.values[segment.attrName];
+        // Both should be strings
+        if (String(actualValue) !== String(segment.attrValue)) {
+          return false;
+        }
+      }
+    }
+
+    // Match position (only for current node)
+    if (segment.position !== undefined) {
+      if (!isCurrentNode) {
+        // Can't check position for ancestor nodes
+        return false;
+      }
+
+      const counter = node.counter ?? 0;
+
+      if (segment.position === 'first' && counter !== 0) {
+        return false;
+      } else if (segment.position === 'odd' && counter % 2 !== 1) {
+        return false;
+      } else if (segment.position === 'even' && counter % 2 !== 0) {
+        return false;
+      } else if (segment.position === 'nth') {
+        if (counter !== segment.positionValue) {
+          return false;
+        }
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Create a snapshot of current state
+   * @returns {Object} State snapshot
+   */
+  snapshot() {
+    return {
+      path: this.path.map(node => ({ ...node })),
+      siblingStacks: this.siblingStacks.map(map => new Map(map))
+    };
+  }
+
+  /**
+   * Restore state from snapshot
+   * @param {Object} snapshot - State snapshot
+   */
+  restore(snapshot) {
+    this.path = snapshot.path.map(node => ({ ...node }));
+    this.siblingStacks = snapshot.siblingStacks.map(map => new Map(map));
+  }
+}

package/src/index.js

@@ -0,0 +1,28 @@
+/**
+ * fast-xml-tagger - XML/JSON path matching library
+ * 
+ * Provides efficient path tracking and pattern matching for XML/JSON parsers.
+ * 
+ * @example
+ * import { Expression, Matcher } from 'fast-xml-tagger';
+ * 
+ * // Create expression (parse once)
+ * const expr = new Expression("root.users.user[id]");
+ * 
+ * // Create matcher (track path)
+ * const matcher = new Matcher();
+ * matcher.push("root", [], {}, 0);
+ * matcher.push("users", [], {}, 0);
+ * matcher.push("user", ["id", "type"], { id: "123", type: "admin" }, 0);
+ * 
+ * // Match
+ * if (matcher.matches(expr)) {
+ *   console.log("Match found!");
+ * }
+ */
+
+import Expression from './Expression.js';
+import Matcher from './Matcher.js';
+
+export { Expression, Matcher };
+export default { Expression, Matcher };