# path-expression-matcher
Efficient path tracking and pattern matching for XML, JSON, YAML or any other parsers.
## 🎯 Purpose
`path-expression-matcher` provides three 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
- **`MatcherView`**: A lightweight read-only view of a `Matcher`, safe to pass to callbacks
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"
}
// 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
```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 ``, the second `` has position=2 but counter=1.
### Namespaces
```javascript
"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
```javascript
"..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
```javascript
new Expression(pattern, options = {}, data)
```
**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: '/' });
const expr3 = new Expression("root/users/user", { separator: '/' }, { extra: "data"});
console.log(expr3.data) // { extra: "data" }
```
#### 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, 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:**
```javascript
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:
```xml
```
##### `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
}
```
#### `matchesAny(exprSet)` → `boolean`
Please check `ExpressionSet` class for more details.
```javascript
const matcher = new Matcher();
const exprSet = new ExpressionSet();
exprSet.add(new Expression("root.users.user"));
exprSet.add(new Expression("root.config.*"));
exprSet.seal();
if (matcher.matchesAny(exprSet)) {
// Current path matches any expression in the set
}
```
##### `getCurrentTag()`
Get current tag name.
```javascript
const tag = matcher.getCurrentTag(); // "user"
```
##### `getCurrentNamespace()`
Get current namespace.
```javascript
const ns = matcher.getCurrentNamespace(); // "soap" or undefined
```
##### `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?, 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)
```javascript
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.
```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);
```
#### Read-Only Access
##### `readOnly()`
Returns a **`MatcherView`** — a lightweight, live read-only view of the matcher. All query and inspection methods work normally and always reflect the current state of the underlying matcher. Mutation methods (`push`, `pop`, `reset`, `updateCurrent`, `restore`) simply don't exist on `MatcherView`, so misuse is caught at **compile time** by TypeScript rather than at runtime.
The **same instance** is returned on every call — no allocation occurs per invocation. This is the recommended way to share the matcher with callbacks, plugins, or any external code that only needs to inspect the current path.
```javascript
const view = matcher.readOnly();
// Same reference every time — safe to cache
view === matcher.readOnly(); // true
```
**What works on the view:**
```javascript
view.matches(expr) // ✓ pattern matching
view.getCurrentTag() // ✓ current tag name
view.getCurrentNamespace() // ✓ current namespace
view.getAttrValue("id") // ✓ attribute value
view.hasAttr("id") // ✓ attribute presence check
view.getPosition() // ✓ sibling position
view.getCounter() // ✓ occurrence counter
view.getDepth() // ✓ path depth
view.toString() // ✓ path as string
view.toArray() // ✓ path as array
```
**What doesn't exist (compile-time error in TypeScript):**
```javascript
view.push("child", {}) // ✗ Property 'push' does not exist on type 'MatcherView'
view.pop() // ✗ Property 'pop' does not exist on type 'MatcherView'
view.reset() // ✗ Property 'reset' does not exist on type 'MatcherView'
view.updateCurrent({}) // ✗ Property 'updateCurrent' does not exist on type 'MatcherView'
view.restore(snapshot) // ✗ Property 'restore' does not exist on type 'MatcherView'
```
**The view is live** — it always reflects the current state of the underlying matcher.
```javascript
const matcher = new Matcher();
const view = matcher.readOnly();
matcher.push("root");
view.getDepth(); // 1 — immediately reflects the push
matcher.push("users");
view.getDepth(); // 2 — still live
```
## 💡 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)
```
### Example 8: Passing a Read-Only View to External Consumers
When passing the matcher into callbacks, plugins, or other code you don't control, use `readOnly()` to get a `MatcherView` — it can inspect but never mutate parser state.
```javascript
import { Expression, Matcher } from 'path-expression-matcher';
const matcher = new Matcher();
const adminExpr = new Expression("..user[type=admin]");
function parseTag(tagName, attrs, onTag) {
matcher.push(tagName, attrs);
// Pass MatcherView — consumer can inspect but not mutate
onTag(matcher.readOnly());
matcher.pop();
}
// Safe consumer — can only read
function myPlugin(view) {
if (view.matches(adminExpr)) {
console.log("Admin at path:", view.toString());
console.log("Depth:", view.getDepth());
console.log("ID:", view.getAttrValue("id"));
}
}
// view.push(...) or view.reset() don't exist on MatcherView —
// TypeScript catches misuse at compile time.
parseTag("user", { id: "1", type: "admin" }, myPlugin);
```
```javascript
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):
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 with ExpressionSet (Recommended)
For checking multiple patterns on every tag, use `ExpressionSet` instead of a manual loop.
It pre-indexes expressions at build time so each call to `matchesAny()` does an O(1) bucket
lookup rather than a full O(N) scan:
```javascript
import { Expression, ExpressionSet, Matcher } from 'path-expression-matcher';
// Build once at config/startup time
const stopNodes = new ExpressionSet();
stopNodes
.add(new Expression('root.users.user'))
.add(new Expression('root.config.*'))
.add(new Expression('..script'))
.seal(); // prevent accidental mutation during parsing
// Per-tag — hot path
if (stopNodes.matchesAny(matcher)) {
// handle stop node
}
```
This replaces the manual loop pattern:
```javascript
// ❌ Before — O(N) per tag
function isStopNode(expressions, matcher) {
for (let i = 0; i < expressions.length; i++) {
if (matcher.matches(expressions[i])) return true;
}
return false;
}
// ✅ After — O(1) lookup per tag
const stopNodes = new ExpressionSet();
stopNodes.addAll(expressions);
stopNodes.matchesAny(matcher);
//or matcher.matchesAny(stopNodes)
```
---
## 📦 ExpressionSet API
`ExpressionSet` is an indexed collection of `Expression` objects designed for efficient
bulk matching. Build it once from your config, then call `matchesAny()` on every tag.
### Constructor
```javascript
const set = new ExpressionSet();
```
### `add(expression)` → `this`
Add a single `Expression`. Duplicate patterns (same pattern string) are silently ignored.
Returns `this` for chaining. Throws `TypeError` if the set is sealed.
```javascript
set.add(new Expression('root.users.user'));
set.add(new Expression('..script'));
```
### `addAll(expressions)` → `this`
Add an array of `Expression` objects at once. Returns `this` for chaining.
```javascript
set.addAll(config.stopNodes.map(p => new Expression(p)));
```
### `has(expression)` → `boolean`
Check whether an expression with the same pattern is already present.
```javascript
set.has(new Expression('root.users.user')); // true / false
```
### `seal()` → `this`
Prevent further additions. Any subsequent call to `add()` or `addAll()` throws a `TypeError`.
Useful to guard against accidental mutation once parsing has started.
```javascript
const stopNodes = new ExpressionSet();
stopNodes.addAll(patterns).seal();
stopNodes.add(new Expression('root.extra')); // ❌ TypeError: ExpressionSet is sealed
```
### `size` → `number`
Number of distinct expressions in the set.
```javascript
set.size; // 3
```
### `isSealed` → `boolean`
Whether `seal()` has been called.
### `matchesAny(matcher)` → `boolean`
Returns `true` if the matcher's current path matches **any** expression in the set.
Accepts both a `Matcher` instance and a `MatcherView`.
```javascript
if (stopNodes.matchesAny(matcher)) { /* ... */ }
if (stopNodes.matchesAny(matcher.readOnly())) { /* ... */ } // also works
```
**How indexing works:** expressions are bucketed at `add()` time, not at match time.
| Expression type | Bucket | Lookup cost |
|---|---|---|
| Fixed path, concrete tag (`root.users.user`) | `depth:tag` map | O(1) |
| Fixed path, wildcard tag (`root.config.*`) | `depth` map | O(1) |
| Deep wildcard (`..script`) | flat list | O(D) — always scanned |
In practice, deep-wildcard expressions are rare in configs, so the list stays small.
### `findMatch(matcher)` → `Expression`
Returns the Expression instance that matched the current path. Accepts both a `Matcher` instance and a `MatcherView`.
```javascript
const node = stopNodes.findMatch(matcher);
```
### Example 7: ExpressionSet in a real parser loop
```javascript
import { XMLParser } from 'fast-xml-parser';
import { Expression, ExpressionSet, Matcher } from 'path-expression-matcher';
// Config-time setup
const stopNodes = new ExpressionSet();
stopNodes
.addAll(['script', 'style'].map(t => new Expression(`..${t}`)))
.seal();
const matcher = new Matcher();
const parser = new XMLParser({
onOpenTag(tagName, attrs) {
matcher.push(tagName, attrs);
if (stopNodes.matchesAny(matcher)) {
// treat as stop node
}
},
onCloseTag() {
matcher.pop();
},
});
```
## 🔗 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;
}
});
```
## 📄 License
MIT
## 🤝 Contributing
Issues and PRs welcome! This package is designed to be used by XML/JSON parsers like fast-xml-parser. But can be used with any formar parser.