path-expression-matcher

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 and similar tools.

📦 Installation

npm install path-expression-matcher

🚀 Quick Start

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"
}

// Namespace support
const nsExpr = new Expression("soap::Envelope.soap::Body..ns::UserId");
matcher.push("Envelope", null, "soap");
matcher.push("Body", null, "soap");
matcher.push("UserId", null, "ns");
console.log(matcher.toString()); // "soap:Envelope.soap:Body.ns:UserId"

📖 Pattern Syntax

Basic Paths

"root.users.user"           // Exact path match
"*.users.user"              // Wildcard: any parent
"root.*.user"               // Wildcard: any middle
"root.users.*"              // Wildcard: any child

Deep Wildcard

"..user"                    // user anywhere in tree
"root..user"                // user anywhere under root
"..users..user"             // users somewhere, then user below it

Attribute Matching

"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

"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.

Namespaces

"ns::user"                  // user with namespace "ns"
"soap::Envelope"            // Envelope with namespace "soap"
"ns::user[id]"              // user with namespace "ns" and "id" attribute
"ns::user:first"            // First user with namespace "ns"
"*::user"                   // user with any namespace
"..ns::item"                // item with namespace "ns" anywhere in tree
"soap::Envelope.soap::Body" // Nested namespaced elements
"ns::first"                 // Tag named "first" with namespace "ns" (NO ambiguity!)

Namespace syntax:

• Use double colon (::) for namespace: ns::tag
• Use single colon (:) for position: tag:first
• Combined: ns::tag:first (namespace + tag + position)

Namespace matching rules:

• Pattern ns::user matches only nodes with namespace "ns" and tag "user"
• Pattern user (no namespace) matches nodes with tag "user" regardless of namespace
• Pattern *::user matches tag "user" with any namespace (wildcard namespace)
• Namespaces are tracked separately for counter/position (e.g., ns1::item and ns2::item have independent counters)

Wildcard Differences

Single wildcard (*) - Matches exactly ONE level:

• "*.fix1" matches root.fix1 (2 levels) ✅
• "*.fix1" does NOT match root.another.fix1 (3 levels) ❌
• Path depth MUST equal pattern depth

Deep wildcard (..) - Matches ZERO or MORE levels:

• "..fix1" matches root.fix1 ✅
• "..fix1" matches root.another.fix1 ✅
• "..fix1" matches a.b.c.d.fix1 ✅
• Works at any depth

Combined Patterns

"..user[id]:first"              // First user with id, anywhere
"root..user[type=admin]"        // Admin user under root
"ns::user[id]:first"            // First namespaced user with id
"soap::Envelope..ns::UserId"    // UserId with namespace ns under SOAP envelope

🔧 API Reference

Expression

Constructor

new Expression(pattern, options)

Parameters:

• pattern (string): Pattern to parse
• options.separator (string): Path separator (default: '.')

Example:

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

new Matcher(options)

Parameters:

• options.separator (string): Default path separator (default: '.')

Path Tracking Methods

push(tagName, attrValues, namespace)

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)
• namespace (string, optional): Namespace for the tag

Example:

matcher.push("user", { id: "123", type: "admin" });
matcher.push("item");  // No attributes
matcher.push("Envelope", null, "soap");  // With namespace
matcher.push("Body", { version: "1.1" }, "soap");  // With both

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:

<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.

matcher.pop();

updateCurrent(attrValues)

Update current node's attributes (useful when attributes are parsed after push).

matcher.push("user");  // Don't know values yet
// ... parse attributes ...
matcher.updateCurrent({ id: "123" });

reset()

Clear the entire path.

matcher.reset();

Query Methods

matches(expression)

Check if current path matches an Expression.

const expr = new Expression("root.users.user");
if (matcher.matches(expr)) {
  // Current path matches
}

getCurrentTag()

Get current tag name.

const tag = matcher.getCurrentTag(); // "user"

getCurrentNamespace()

Get current namespace.

const ns = matcher.getCurrentNamespace(); // "soap" or undefined

getAttrValue(attrName)

Get attribute value of current node.

const id = matcher.getAttrValue("id"); // "123"

hasAttr(attrName)

Check if current node has an attribute.

if (matcher.hasAttr("id")) {
  // Current node has "id" attribute
}

getPosition()

Get sibling position of current node (child index in parent).

const position = matcher.getPosition(); // 0, 1, 2, ...

getCounter()

Get repeat counter of current node (occurrence count of this tag name).

const counter = matcher.getCounter(); // 0, 1, 2, ...

getIndex() (deprecated)

Alias for getPosition(). Use getPosition() or getCounter() instead for clarity.

const index = matcher.getIndex(); // Same as getPosition()

getDepth()

Get current path depth.

const depth = matcher.getDepth(); // 3 for "root.users.user"

toString(separator?, includeNamespace?)

Get path as string.

Parameters:

• separator (string, optional): Path separator (uses default if not provided)
• includeNamespace (boolean, optional): Whether to include namespaces (default: true)

const path = matcher.toString();           // "root.ns:user.item"
const path2 = matcher.toString('/');       // "root/ns:user/item"
const path3 = matcher.toString('.', false); // "root.user.item" (no namespaces)

toArray()

Get path as array.

const arr = matcher.toArray(); // ["root", "users", "user"]

State Management

snapshot()

Create a snapshot of current state.

const snapshot = matcher.snapshot();

restore(snapshot)

Restore from a snapshot.

matcher.restore(snapshot);

💡 Usage Examples

Example 1: XML Parser with stopNodes

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

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

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

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

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

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)

Example 7: Namespace Support (XML/SOAP)

const matcher = new Matcher();
const soapExpr = new Expression("soap::Envelope.soap::Body..ns::UserId");

// Parse SOAP document
matcher.push("Envelope", { xmlns: "..." }, "soap");
matcher.push("Body", null, "soap");
matcher.push("GetUserRequest", null, "ns");
matcher.push("UserId", null, "ns");

// Match namespaced pattern
if (matcher.matches(soapExpr)) {
  console.log("Found UserId in SOAP body");
  console.log(matcher.toString()); // "soap:Envelope.soap:Body.ns:GetUserRequest.ns:UserId"
}

// Namespace-specific counters
matcher.reset();
matcher.push("root");
matcher.push("item", null, "ns1");  // ns1::item counter=0
matcher.pop();
matcher.push("item", null, "ns2");  // ns2::item counter=0 (different namespace)
matcher.pop();
matcher.push("item", null, "ns1");  // ns1::item counter=1

const firstNs1Item = new Expression("root.ns1::item:first");
console.log(matcher.matches(firstNs1Item)); // false (counter=1)

const secondNs1Item = new Expression("root.ns1::item:nth(1)");
console.log(matcher.matches(secondNs1Item)); // true

// NO AMBIGUITY: Tags named after position keywords
matcher.reset();
matcher.push("root");
matcher.push("first", null, "ns");  // Tag named "first" with namespace

const expr = new Expression("root.ns::first");
console.log(matcher.matches(expr)); // true - matches namespace "ns", tag "first"

🏗️ 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):

• Start at current node
• Match segments from pattern end to start
• Attribute checking only works for current node (ancestors have no attribute data)
• 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)

// ✅ GOOD: Parse once, reuse many times
const expr = new Expression("..user[id]");

for (let i = 0; i < 1000; i++) {
  if (matcher.matches(expr)) {
    // ...
  }
}

// ❌ BAD: Parse on every iteration
for (let i = 0; i < 1000; i++) {
  if (matcher.matches(new Expression("..user[id]"))) {
    // ...
  }
}

Batch Pattern Checking

// 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:

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

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.