devbrain-cli 0.2.0 → 0.3.0

package/dist/temp-prefix/node_modules/devbrain-cli/node_modules/path-expression-matcher/README.md

@@ -0,0 +1,947 @@
+# path-expression-matcher
+
+[![path-expression-matcher downloads](https://img.shields.io/npm/dw/path-expression-matcher.svg)](https://npm-compare.com/path-expression-matcher) 
+[![path-expression-matcher version](https://img.shields.io/npm/v/path-expression-matcher.svg)](https://www.npmjs.com/package/path-expression-matcher)
+[![path-expression-matcher license](https://img.shields.io/npm/l/path-expression-matcher.svg)](https://github.com/NaturalIntelligence/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)
+```
+
+> **Note:** Attribute conditions in expressions only ever look at the **current** (last) node in the path — `..user` matches `user` at any depth, but bracket conditions like `[lang]` still apply to `user` itself, never to an ancestor tag. To check an *ancestor's* attribute (e.g. "is there a `lang` attribute somewhere above this node?"), use `push(..., { keep: [...] })` with `getAnyParentAttr()` / `hasAnyParentAttr()` — see [Ancestor Attributes (`keep`)](#ancestor-attributes-keep) below.
+
+### 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.
+
+### 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, options)`
+
+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
+- `options` (object, optional):
+  - `keep` (string[], optional): Names of attributes (from `attrValues`) to retain for ancestor lookup via `getAnyParentAttr()` / `hasAnyParentAttr()`, even after this node is no longer the current node. See [Ancestor Attributes (`keep`)](#ancestor-attributes-keep).
+
+**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
+matcher.push("Body", { version: "1.1" }, "soap", { keep: ["version"] });  // Retain "version" for descendants
+```
+
+**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
+}
+```
+
+#### `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
+}
+```
+
+##### `getAnyParentAttr(attrName)`
+
+Get the value of an attribute that was explicitly **kept** (via `push(..., { keep: [...] })`) by the current node or any ancestor. Unlike `getAttrValue()`, this works regardless of how far the path has descended since the attribute was pushed — but only for names that were marked with `keep` at push time. If the same name was kept at multiple depths, the **nearest** (most recent) one wins.
+
+```javascript
+matcher.push("Body", { version: "1.1" }, "soap", { keep: ["version"] });
+matcher.push("GetUserRequest");
+matcher.push("UserId");
+
+matcher.getAttrValue("version");     // undefined — Body is no longer current
+matcher.getAnyParentAttr("version"); // "1.1" — still reachable, because it was kept
+```
+
+##### `hasAnyParentAttr(attrName)`
+
+Check whether the current node or any ancestor kept the given attribute via `push(..., { keep: [...] })`.
+
+```javascript
+if (matcher.hasAnyParentAttr("version")) {
+  // Some node on the path (current or ancestor) kept "version"
+}
+```
+
+##### `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
+```
+
+> Need to check an attribute from an *ancestor* node, not just the current one? See [Example 5b](#example-5b-ancestor-attributes-keep) and [Ancestor Attributes (`keep`)](#ancestor-attributes-keep).
+
+### Example 5b: Ancestor Attributes (`keep`)
+
+`getAttrValue()` / `hasAttr()` only ever see the **current** node — by design, ancestor attribute values are discarded as soon as you push past them, to keep memory usage low. If you know in advance that a specific attribute (e.g. a SOAP envelope's `version`, or `xml:space`) will matter much deeper in the tree, mark it to be **kept**:
+
+```javascript
+const matcher = new Matcher();
+matcher.push("Envelope", null, "soap");
+matcher.push("Body", { version: "1.1" }, "soap", { keep: ["version"] });
+matcher.push("GetUserRequest", { id: "42" });
+matcher.push("UserId");
+
+// Ordinary attribute access only sees the current node:
+console.log(matcher.getAttrValue("version"));     // undefined
+
+// getAnyParentAttr/hasAnyParentAttr still see it, however deep we've gone:
+console.log(matcher.hasAnyParentAttr("version")); // true
+console.log(matcher.getAnyParentAttr("version")); // "1.1"
+
+matcher.pop(); matcher.pop(); matcher.pop(); // back to Envelope
+console.log(matcher.hasAnyParentAttr("version")); // false — Body (and its kept attrs) was popped
+```
+
+**When to use this:** only for the small number of attributes you specifically know you'll need many levels deeper — not as a general substitute for `getAttrValue()`. Each name passed to `keep` adds a tiny, constant amount of bookkeeping at `push()` time; lookups scan only the kept-attributes list (typically 0-3 entries), never the full path, so cost does not grow with document depth.
+
+### 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, **by default**
+- For 1M nodes with 3 attributes each, saves ~50MB vs storing attribute names
+
+### Ancestor Attributes (`keep`)
+
+The trade-off above is the right default, but XML/SOAP documents occasionally have a handful of attributes — `xml:space`, a SOAP envelope's `version`, a feature-flag at the document root — that genuinely need to be visible many levels deeper. Rather than retaining *all* attribute values for *every* node (defeating the memory savings above), `push()` accepts an explicit opt-in:
+
+```javascript
+matcher.push("Body", { version: "1.1" }, "soap", { keep: ["version"] });
+```
+
+Only the named attribute(s) are copied into a small side-stack (`_keptAttrs`), independent of the normal per-node `values`. Reachable later via `getAnyParentAttr(name)` / `hasAnyParentAttr(name)` regardless of depth — see [Example 5b](#example-5b-ancestor-attributes-keep).
+
+**Why this stays cheap:**
+- Pushing without `options` costs two extra property reads — no allocation, no measurable overhead (benchmarked: within run-to-run noise vs. plain `push()`).
+- Lookups scan only the kept-attributes stack, not the full path — cost is proportional to *how many distinct attributes are currently kept* (typically 0-3 in real usage), not to document depth.
+- `pop()` truncates kept entries belonging to the popped subtree in the same backward-scan style, so the stack never grows unbounded.
+- The core `matches()` / `_matchSegment` pattern-matching path is completely unaffected — `keep` is a separate, opt-in mechanism with no new expression syntax.
+
+This is intentionally a narrow escape hatch, not a general "remember everything" toggle — overusing `keep` (e.g. keeping every attribute on every node) reintroduces the same memory cost this library avoids by default.
+
+### 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 *expression* conditions (`[attr=value]`) only apply to the current node — ancestors have no attribute data in the path itself. For genuinely ancestor-scoped checks outside of expression matching, use `keep` (above).
+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 (O(k) additionally when `options.keep` is used, where k = number of kept attribute names — typically 0-3)
+- **Pattern matching:** O(n*m) where n = path depth, m = pattern segments
+- **Ancestor attribute lookup:** O(k) where k = number of currently-kept attributes, independent of path depth
+- **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.