path-expression-matcher 1.0.0 → 1.1.1

package/README.md

@@ -37,6 +37,13 @@ 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
@@ -78,11 +85,50 @@ if (matcher.matches(expr)) {
 
 **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
+"..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
@@ -125,18 +171,21 @@ new Matcher(options)
 
 #### Path Tracking Methods
 
-##### `push(tagName, attrValues)`
+##### `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:**
@@ -199,6 +248,14 @@ Get current tag name.
 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.
@@ -249,13 +306,18 @@ Get current path depth.
 const depth = matcher.getDepth(); // 3 for "root.users.user"
 ```
 
-##### `toString(separator?)`
+##### `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.users.user"
-const path2 = matcher.toString('/'); // "root/users/user"
+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()`
@@ -419,6 +481,48 @@ const expr = new Expression("root.item:first");
 console.log(matcher.matches(expr)); // false (counter=1, not 0)
 ```
 
+### Example 7: Namespace Support (XML/SOAP)
+
+```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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "path-expression-matcher",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Efficient path tracking and pattern matching for XML/JSON parsers",
   "main": "src/index.js",
   "type": "module",
@@ -10,7 +10,7 @@
     "./Matcher": "./src/Matcher.js"
   },
   "scripts": {
-    "test": "node test/test.js"
+    "test": "node test/namespace_test.js && node test/test.js"
   },
   "keywords": [
     "xml",

package/src/Expression.js

@@ -76,51 +76,120 @@ export default class Expression {
   /**
    * Parse a single segment
    * @private
-   * @param {string} part - Segment string (e.g., "user", "user[id]", "user:first")
+   * @param {string} part - Segment string (e.g., "user", "ns::user", "user[id]", "ns::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+\))?))?$/);
+    // CRITICAL: Handle wildcard FIRST (before any other parsing)
+    if (part === '*') {
+      segment.tag = '*';
+      return segment;
+    }
 
-    if (!match) {
-      throw new Error(`Invalid segment pattern: ${part}`);
+    // NEW NAMESPACE SYNTAX (v2.0):
+    // ============================
+    // Namespace uses DOUBLE colon (::)
+    // Position uses SINGLE colon (:)
+    // 
+    // Examples:
+    //   "user"              → tag
+    //   "user:first"        → tag + position
+    //   "user[id]"          → tag + attribute
+    //   "user[id]:first"    → tag + attribute + position
+    //   "ns::user"          → namespace + tag
+    //   "ns::user:first"    → namespace + tag + position
+    //   "ns::user[id]"      → namespace + tag + attribute
+    //   "ns::user[id]:first" → namespace + tag + attribute + position
+    //   "ns::first"         → namespace + tag named "first" (NO ambiguity!)
+    //
+    // This eliminates all ambiguity:
+    //   :: = namespace separator
+    //   :  = position selector
+    //   [] = attributes
+
+    // Step 1: Extract brackets [attr] or [attr=value]
+    let bracketContent = null;
+    let withoutBrackets = part;
+
+    const bracketMatch = part.match(/^([^\[]+)(\[[^\]]*\])(.*)$/);
+    if (bracketMatch) {
+      withoutBrackets = bracketMatch[1] + bracketMatch[3];
+      if (bracketMatch[2]) {
+        const content = bracketMatch[2].slice(1, -1);
+        if (content) {
+          bracketContent = content;
+        }
+      }
+    }
+
+    // Step 2: Check for namespace (double colon ::)
+    let namespace = undefined;
+    let tagAndPosition = withoutBrackets;
+
+    if (withoutBrackets.includes('::')) {
+      const nsIndex = withoutBrackets.indexOf('::');
+      namespace = withoutBrackets.substring(0, nsIndex).trim();
+      tagAndPosition = withoutBrackets.substring(nsIndex + 2).trim(); // Skip ::
+
+      if (!namespace) {
+        throw new Error(`Invalid namespace in pattern: ${part}`);
+      }
     }
 
-    segment.tag = match[1].trim();
+    // Step 3: Parse tag and position (single colon :)
+    let tag = undefined;
+    let positionMatch = null;
 
-    // Parse attribute condition [attr] or [attr=value]
-    if (match[2]) {
-      const attrExpr = match[2];
+    if (tagAndPosition.includes(':')) {
+      const colonIndex = tagAndPosition.lastIndexOf(':'); // Use last colon for position
+      const tagPart = tagAndPosition.substring(0, colonIndex).trim();
+      const posPart = tagAndPosition.substring(colonIndex + 1).trim();
 
-      if (attrExpr.includes('=')) {
-        const eqIndex = attrExpr.indexOf('=');
-        const attrName = attrExpr.substring(0, eqIndex).trim();
-        const attrValue = attrExpr.substring(eqIndex + 1).trim();
+      // Verify position is a valid keyword
+      const isPositionKeyword = ['first', 'last', 'odd', 'even'].includes(posPart) ||
+        /^nth\(\d+\)$/.test(posPart);
 
-        segment.attrName = attrName;
-        segment.attrValue = attrValue;
+      if (isPositionKeyword) {
+        tag = tagPart;
+        positionMatch = posPart;
       } else {
-        segment.attrName = attrExpr.trim();
+        // Not a valid position keyword, treat whole thing as tag
+        tag = tagAndPosition;
       }
+    } else {
+      tag = tagAndPosition;
     }
 
-    // Parse position selector :first, :nth(n), :odd, :even
-    if (match[3]) {
-      const posExpr = match[3];
+    if (!tag) {
+      throw new Error(`Invalid segment pattern: ${part}`);
+    }
+
+    segment.tag = tag;
+    if (namespace) {
+      segment.namespace = namespace;
+    }
+
+    // Step 4: Parse attributes
+    if (bracketContent) {
+      if (bracketContent.includes('=')) {
+        const eqIndex = bracketContent.indexOf('=');
+        segment.attrName = bracketContent.substring(0, eqIndex).trim();
+        segment.attrValue = bracketContent.substring(eqIndex + 1).trim();
+      } else {
+        segment.attrName = bracketContent.trim();
+      }
+    }
 
-      // Check for :nth(n) pattern
-      const nthMatch = posExpr.match(/^nth\((\d+)\)$/);
+    // Step 5: Parse position selector
+    if (positionMatch) {
+      const nthMatch = positionMatch.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}`);
+        segment.position = positionMatch;
       }
     }
 

package/src/Matcher.js

@@ -33,8 +33,9 @@ export default class Matcher {
    * 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)
+   * @param {string} namespace - Namespace for the tag (optional)
    */
-  push(tagName, attrValues = null) {
+  push(tagName, attrValues = null, namespace = null) {
     // Remove values from previous current node (now becoming ancestor)
     if (this.path.length > 0) {
       const prev = this.path[this.path.length - 1];
@@ -49,8 +50,11 @@ export default class Matcher {
 
     const siblings = this.siblingStacks[currentLevel];
 
+    // Create a unique key for sibling tracking that includes namespace
+    const siblingKey = namespace ? `${namespace}:${tagName}` : tagName;
+
     // Calculate counter (how many times this tag appeared at this level)
-    const counter = siblings.get(tagName) || 0;
+    const counter = siblings.get(siblingKey) || 0;
 
     // Calculate position (total children at this level so far)
     let position = 0;
@@ -59,7 +63,7 @@ export default class Matcher {
     }
 
     // Update sibling count for this tag
-    siblings.set(tagName, counter + 1);
+    siblings.set(siblingKey, counter + 1);
 
     // Create new node
     const node = {
@@ -68,6 +72,11 @@ export default class Matcher {
       counter: counter
     };
 
+    // Store namespace if provided
+    if (namespace !== null && namespace !== undefined) {
+      node.namespace = namespace;
+    }
+
     // Store values only for current node
     if (attrValues !== null && attrValues !== undefined) {
       node.values = attrValues;
@@ -87,9 +96,11 @@ export default class Matcher {
 
     const node = this.path.pop();
 
-    // Clean up sibling tracking for this level
-    if (this.siblingStacks[this.path.length]) {
-      delete this.siblingStacks[this.path.length];
+    // Clean up sibling tracking for levels deeper than current
+    // After pop, path.length is the new depth
+    // We need to clean up siblingStacks[path.length + 1] and beyond
+    if (this.siblingStacks.length > this.path.length + 1) {
+      this.siblingStacks.length = this.path.length + 1;
     }
 
     return node;
@@ -117,6 +128,14 @@ export default class Matcher {
     return this.path.length > 0 ? this.path[this.path.length - 1].tag : undefined;
   }
 
+  /**
+   * Get current namespace
+   * @returns {string|undefined}
+   */
+  getCurrentNamespace() {
+    return this.path.length > 0 ? this.path[this.path.length - 1].namespace : undefined;
+  }
+
   /**
    * Get current node's attribute value
    * @param {string} attrName - Attribute name
@@ -177,11 +196,17 @@ export default class Matcher {
   /**
    * Get path as string
    * @param {string} separator - Optional separator (uses default if not provided)
+   * @param {boolean} includeNamespace - Whether to include namespace in output (default: true)
    * @returns {string}
    */
-  toString(separator) {
+  toString(separator, includeNamespace = true) {
     const sep = separator || this.separator;
-    return this.path.map(n => n.tag).join(sep);
+    return this.path.map(n => {
+      if (includeNamespace && n.namespace) {
+        return `${n.namespace}:${n.tag}`;
+      }
+      return n.tag;
+    }).join(sep);
   }
 
   /**
@@ -311,6 +336,15 @@ export default class Matcher {
       return false;
     }
 
+    // Match namespace if specified in segment
+    if (segment.namespace !== undefined) {
+      // Segment has namespace - node must match it
+      if (segment.namespace !== '*' && segment.namespace !== node.namespace) {
+        return false;
+      }
+    }
+    // If segment has no namespace, it matches nodes with or without namespace
+
     // 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) {