@cdklabs/cdk-ecs-codedeploy 0.0.433 → 0.0.434

package/node_modules/@aws-sdk/xml-builder/node_modules/fast-xml-parser/src/xmlparser/XMLParser.js

@@ -35,7 +35,7 @@ export default class XMLParser {
         orderedObjParser.addExternalEntities(this.externalEntities);
         const orderedResult = orderedObjParser.parseXml(xmlData);
         if (this.options.preserveOrder || orderedResult === undefined) return orderedResult;
-        else return prettify(orderedResult, this.options);
+        else return prettify(orderedResult, this.options, orderedObjParser.matcher, orderedObjParser.readonlyMatcher);
     }
 
     /**
@@ -68,4 +68,4 @@ export default class XMLParser {
     static getMetaDataSymbol() {
         return XmlNode.getMetaDataSymbol();
     }
-}
+}

package/node_modules/@aws-sdk/xml-builder/node_modules/fast-xml-parser/src/xmlparser/node2json.js

@@ -1,35 +1,65 @@
 'use strict';
 
 import XmlNode from './xmlNode.js';
+import { Matcher } from 'path-expression-matcher';
 
 const METADATA_SYMBOL = XmlNode.getMetaDataSymbol();
 
+/**
+ * Helper function to strip attribute prefix from attribute map
+ * @param {object} attrs - Attributes with prefix (e.g., {"@_class": "code"})
+ * @param {string} prefix - Attribute prefix to remove (e.g., "@_")
+ * @returns {object} Attributes without prefix (e.g., {"class": "code"})
+ */
+function stripAttributePrefix(attrs, prefix) {
+  if (!attrs || typeof attrs !== 'object') return {};
+  if (!prefix) return attrs;
+
+  const rawAttrs = {};
+  for (const key in attrs) {
+    if (key.startsWith(prefix)) {
+      const rawName = key.substring(prefix.length);
+      rawAttrs[rawName] = attrs[key];
+    } else {
+      // Attribute without prefix (shouldn't normally happen, but be safe)
+      rawAttrs[key] = attrs[key];
+    }
+  }
+  return rawAttrs;
+}
+
 /**
  * 
  * @param {array} node 
  * @param {any} options 
+ * @param {Matcher} matcher - Path matcher instance
  * @returns 
  */
-export default function prettify(node, options) {
-  return compress(node, options);
+export default function prettify(node, options, matcher, readonlyMatcher) {
+  return compress(node, options, matcher, readonlyMatcher);
 }
 
 /**
- * 
  * @param {array} arr 
  * @param {object} options 
- * @param {string} jPath 
+ * @param {Matcher} matcher - Path matcher instance
  * @returns object
  */
-function compress(arr, options, jPath) {
+function compress(arr, options, matcher, readonlyMatcher) {
   let text;
   const compressedObj = {}; //This is intended to be a plain object
   for (let i = 0; i < arr.length; i++) {
     const tagObj = arr[i];
     const property = propName(tagObj);
-    let newJpath = "";
-    if (jPath === undefined) newJpath = property;
-    else newJpath = jPath + "." + property;
+
+    // Push current property to matcher WITH RAW ATTRIBUTES (no prefix)
+    if (property !== undefined && property !== options.textNodeName) {
+      const rawAttrs = stripAttributePrefix(
+        tagObj[":@"] || {},
+        options.attributeNamePrefix
+      );
+      matcher.push(property, rawAttrs);
+    }
 
     if (property === options.textNodeName) {
       if (text === undefined) text = tagObj[property];
@@ -38,11 +68,11 @@ function compress(arr, options, jPath) {
       continue;
     } else if (tagObj[property]) {
 
-      let val = compress(tagObj[property], options, newJpath);
+      let val = compress(tagObj[property], options, matcher, readonlyMatcher);
       const isLeaf = isLeafTag(val, options);
 
       if (tagObj[":@"]) {
-        assignAttributes(val, tagObj[":@"], newJpath, options);
+        assignAttributes(val, tagObj[":@"], readonlyMatcher, options);
       } else if (Object.keys(val).length === 1 && val[options.textNodeName] !== undefined && !options.alwaysCreateTextNode) {
         val = val[options.textNodeName];
       } else if (Object.keys(val).length === 0) {
@@ -63,12 +93,20 @@ function compress(arr, options, jPath) {
       } else {
         //TODO: if a node is not an array, then check if it should be an array
         //also determine if it is a leaf node
-        if (options.isArray(property, newJpath, isLeaf)) {
+
+        // Pass jPath string or readonlyMatcher based on options.jPath setting
+        const jPathOrMatcher = options.jPath ? readonlyMatcher.toString() : readonlyMatcher;
+        if (options.isArray(property, jPathOrMatcher, isLeaf)) {
           compressedObj[property] = [val];
         } else {
           compressedObj[property] = val;
         }
       }
+
+      // Pop property from matcher after processing
+      if (property !== undefined && property !== options.textNodeName) {
+        matcher.pop();
+      }
     }
 
   }
@@ -89,13 +127,25 @@ function propName(obj) {
   }
 }
 
-function assignAttributes(obj, attrMap, jpath, options) {
+function assignAttributes(obj, attrMap, readonlyMatcher, options) {
   if (attrMap) {
     const keys = Object.keys(attrMap);
     const len = keys.length; //don't make it inline
     for (let i = 0; i < len; i++) {
-      const atrrName = keys[i];
-      if (options.isArray(atrrName, jpath + "." + atrrName, true, true)) {
+      const atrrName = keys[i];  // This is the PREFIXED name (e.g., "@_class")
+
+      // Strip prefix for matcher path (for isArray callback)
+      const rawAttrName = atrrName.startsWith(options.attributeNamePrefix)
+        ? atrrName.substring(options.attributeNamePrefix.length)
+        : atrrName;
+
+      // For attributes, we need to create a temporary path
+      // Pass jPath string or matcher based on options.jPath setting
+      const jPathOrMatcher = options.jPath
+        ? readonlyMatcher.toString() + "." + rawAttrName
+        : readonlyMatcher;
+
+      if (options.isArray(atrrName, jPathOrMatcher, true, true)) {
         obj[atrrName] = [attrMap[atrrName]];
       } else {
         obj[atrrName] = attrMap[atrrName];
@@ -120,4 +170,4 @@ function isLeafTag(obj, options) {
   }
 
   return false;
-}
+}

package/node_modules/{strnum → @aws-sdk/xml-builder/node_modules/strnum}/CHANGELOG.md

@@ -1,6 +1,13 @@
 
-**2.1.1 / 2025-05-15**
-- remove unnecessary check to remove lint error
+**2.2.2 / 2026-03-23**
+- fix for space string
+
+
+**2.2.1 / 2026-03-19**
+- fix false positive for eNotation when no leading zeros
+
+**2.2.0 / 2026-02-28**
+- support infinity
 
 **2.1.0 / 2025-05-01**
 - fix e-notation 

package/node_modules/{strnum → @aws-sdk/xml-builder/node_modules/strnum}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strnum",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "Parse String to Number based on configuration",
   "type": "module",
   "main": "strnum.js",

package/node_modules/{strnum → @aws-sdk/xml-builder/node_modules/strnum}/strnum.js

@@ -20,8 +20,9 @@ export default function toNumber(str, options = {}) {
 
     let trimmedStr = str.trim();
 
-    if (options.skipLike !== undefined && options.skipLike.test(trimmedStr)) return str;
-    else if (str === "0") return 0;
+    if (trimmedStr.length === 0) return str;
+    else if (options.skipLike !== undefined && options.skipLike.test(trimmedStr)) return str;
+    else if (trimmedStr === "0") return 0;
     else if (options.hex && hexRegex.test(trimmedStr)) {
         return parse_int(trimmedStr, 16);
         // }else if (options.oct && octRegex.test(str)) {
@@ -97,11 +98,16 @@ function resolveEnotation(str, trimmedStr, options) {
         else if (leadingZeros.length === 1
             && (notation[3].startsWith(`.${eChar}`) || notation[3][0] === eChar)) {
             return Number(trimmedStr);
-        } else if (options.leadingZeros && !eAdjacentToLeadingZeros) { //accept with leading zeros
-            //remove leading 0s
-            trimmedStr = (notation[1] || "") + notation[3];
+        } else if (leadingZeros.length > 0) {
+            // Has leading zeros — only accept if leadingZeros option allows it
+            if (options.leadingZeros && !eAdjacentToLeadingZeros) {
+                trimmedStr = (notation[1] || "") + notation[3];
+                return Number(trimmedStr);
+            } else return str;
+        } else {
+            // No leading zeros — always valid e-notation, parse it
             return Number(trimmedStr);
-        } else return str;
+        }
     } else {
         return str;
     }

package/node_modules/{strnum → @aws-sdk/xml-builder/node_modules/strnum}/tests/strnum_test.js

@@ -5,6 +5,7 @@ describe("Should convert all the valid numeric strings to number", () => {
         expect(toNumber(undefined)).not.toBeDefined();
         expect(toNumber(null)).toEqual(null);
         expect(toNumber("")).toEqual("");
+        expect(toNumber(" ")).toEqual(" ");
         expect(toNumber("string")).toEqual("string");
         expect(toNumber("e89794659669cb7bb967db73a7ea6889c3891727")).toEqual("e89794659669cb7bb967db73a7ea6889c3891727");
     });
@@ -126,6 +127,8 @@ describe("Should convert all the valid numeric strings to number", () => {
         expect(toNumber("1e-2")).toEqual(0.01);
         expect(toNumber("1e+2")).toEqual(100);
         expect(toNumber("1.e+2")).toEqual(100);
+
+        expect(toNumber("1.5e3", { leadingZeros: false })).toEqual(1500);
     });
 
     it("scientific notation with upper E", () => {

package/node_modules/@aws-sdk/xml-builder/node_modules/strnum/tests/temp.js

@@ -0,0 +1,8 @@
+import toNumber from "../strnum.js";
+
+console.log(toNumber("1.5e3", {leadingZeros: false}))
+// describe("temp", () = {
+
+//   it("scientific notation", () => {
+//     });
+// })

package/node_modules/@aws-sdk/xml-builder/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@aws-sdk/xml-builder",
-  "version": "3.972.11",
+  "version": "3.972.15",
   "description": "XML utilities for the AWS SDK",
   "dependencies": {
     "@smithy/types": "^4.13.1",
-    "fast-xml-parser": "5.4.1",
+    "fast-xml-parser": "5.5.8",
     "tslib": "^2.6.2"
   },
   "scripts": {

package/node_modules/@smithy/config-resolver/dist-cjs/index.js

@@ -12,6 +12,11 @@ const NODE_USE_DUALSTACK_ENDPOINT_CONFIG_OPTIONS = {
     configFileSelector: (profile) => utilConfigProvider.booleanSelector(profile, CONFIG_USE_DUALSTACK_ENDPOINT, utilConfigProvider.SelectorType.CONFIG),
     default: false,
 };
+const nodeDualstackConfigSelectors = {
+    environmentVariableSelector: (env) => utilConfigProvider.booleanSelector(env, ENV_USE_DUALSTACK_ENDPOINT, utilConfigProvider.SelectorType.ENV),
+    configFileSelector: (profile) => utilConfigProvider.booleanSelector(profile, CONFIG_USE_DUALSTACK_ENDPOINT, utilConfigProvider.SelectorType.CONFIG),
+    default: undefined,
+};
 
 const ENV_USE_FIPS_ENDPOINT = "AWS_USE_FIPS_ENDPOINT";
 const CONFIG_USE_FIPS_ENDPOINT = "use_fips_endpoint";
@@ -21,6 +26,11 @@ const NODE_USE_FIPS_ENDPOINT_CONFIG_OPTIONS = {
     configFileSelector: (profile) => utilConfigProvider.booleanSelector(profile, CONFIG_USE_FIPS_ENDPOINT, utilConfigProvider.SelectorType.CONFIG),
     default: false,
 };
+const nodeFipsConfigSelectors = {
+    environmentVariableSelector: (env) => utilConfigProvider.booleanSelector(env, ENV_USE_FIPS_ENDPOINT, utilConfigProvider.SelectorType.ENV),
+    configFileSelector: (profile) => utilConfigProvider.booleanSelector(profile, CONFIG_USE_FIPS_ENDPOINT, utilConfigProvider.SelectorType.CONFIG),
+    default: undefined,
+};
 
 const resolveCustomEndpointsConfig = (input) => {
     const { tls, endpoint, urlParser, useDualstackEndpoint } = input;
@@ -181,6 +191,8 @@ exports.NODE_USE_FIPS_ENDPOINT_CONFIG_OPTIONS = NODE_USE_FIPS_ENDPOINT_CONFIG_OP
 exports.REGION_ENV_NAME = REGION_ENV_NAME;
 exports.REGION_INI_NAME = REGION_INI_NAME;
 exports.getRegionInfo = getRegionInfo;
+exports.nodeDualstackConfigSelectors = nodeDualstackConfigSelectors;
+exports.nodeFipsConfigSelectors = nodeFipsConfigSelectors;
 exports.resolveCustomEndpointsConfig = resolveCustomEndpointsConfig;
 exports.resolveEndpointsConfig = resolveEndpointsConfig;
 exports.resolveRegionConfig = resolveRegionConfig;

package/node_modules/@smithy/config-resolver/dist-es/endpointsConfig/NodeUseDualstackEndpointConfigOptions.js

@@ -7,3 +7,8 @@ export const NODE_USE_DUALSTACK_ENDPOINT_CONFIG_OPTIONS = {
     configFileSelector: (profile) => booleanSelector(profile, CONFIG_USE_DUALSTACK_ENDPOINT, SelectorType.CONFIG),
     default: false,
 };
+export const nodeDualstackConfigSelectors = {
+    environmentVariableSelector: (env) => booleanSelector(env, ENV_USE_DUALSTACK_ENDPOINT, SelectorType.ENV),
+    configFileSelector: (profile) => booleanSelector(profile, CONFIG_USE_DUALSTACK_ENDPOINT, SelectorType.CONFIG),
+    default: undefined,
+};

package/node_modules/@smithy/config-resolver/dist-es/endpointsConfig/NodeUseFipsEndpointConfigOptions.js

@@ -7,3 +7,8 @@ export const NODE_USE_FIPS_ENDPOINT_CONFIG_OPTIONS = {
     configFileSelector: (profile) => booleanSelector(profile, CONFIG_USE_FIPS_ENDPOINT, SelectorType.CONFIG),
     default: false,
 };
+export const nodeFipsConfigSelectors = {
+    environmentVariableSelector: (env) => booleanSelector(env, ENV_USE_FIPS_ENDPOINT, SelectorType.ENV),
+    configFileSelector: (profile) => booleanSelector(profile, CONFIG_USE_FIPS_ENDPOINT, SelectorType.CONFIG),
+    default: undefined,
+};

package/node_modules/@smithy/config-resolver/dist-types/endpointsConfig/NodeUseDualstackEndpointConfigOptions.d.ts

@@ -12,6 +12,12 @@ export declare const CONFIG_USE_DUALSTACK_ENDPOINT = "use_dualstack_endpoint";
  */
 export declare const DEFAULT_USE_DUALSTACK_ENDPOINT = false;
 /**
+ * Don't delete this, used by older clients.
+ * @deprecated replaced by nodeDualstackConfigSelectors in newer clients.
  * @internal
  */
 export declare const NODE_USE_DUALSTACK_ENDPOINT_CONFIG_OPTIONS: LoadedConfigSelectors<boolean>;
+/**
+ * @internal
+ */
+export declare const nodeDualstackConfigSelectors: LoadedConfigSelectors<boolean | undefined>;

package/node_modules/@smithy/config-resolver/dist-types/endpointsConfig/NodeUseFipsEndpointConfigOptions.d.ts

@@ -12,6 +12,12 @@ export declare const CONFIG_USE_FIPS_ENDPOINT = "use_fips_endpoint";
  */
 export declare const DEFAULT_USE_FIPS_ENDPOINT = false;
 /**
+ * Don't delete this, used by older clients.
+ * @deprecated replaced by nodeFipsConfigSelectors in newer clients.
  * @internal
  */
 export declare const NODE_USE_FIPS_ENDPOINT_CONFIG_OPTIONS: LoadedConfigSelectors<boolean>;
+/**
+ * @internal
+ */
+export declare const nodeFipsConfigSelectors: LoadedConfigSelectors<boolean | undefined>;

package/node_modules/@smithy/config-resolver/dist-types/ts3.4/endpointsConfig/NodeUseDualstackEndpointConfigOptions.d.ts

@@ -12,6 +12,12 @@ export declare const CONFIG_USE_DUALSTACK_ENDPOINT = "use_dualstack_endpoint";
  */
 export declare const DEFAULT_USE_DUALSTACK_ENDPOINT = false;
 /**
+ * Don't delete this, used by older clients.
+ * @deprecated replaced by nodeDualstackConfigSelectors in newer clients.
  * @internal
  */
 export declare const NODE_USE_DUALSTACK_ENDPOINT_CONFIG_OPTIONS: LoadedConfigSelectors<boolean>;
+/**
+ * @internal
+ */
+export declare const nodeDualstackConfigSelectors: LoadedConfigSelectors<boolean | undefined>;

package/node_modules/@smithy/config-resolver/dist-types/ts3.4/endpointsConfig/NodeUseFipsEndpointConfigOptions.d.ts

@@ -12,6 +12,12 @@ export declare const CONFIG_USE_FIPS_ENDPOINT = "use_fips_endpoint";
  */
 export declare const DEFAULT_USE_FIPS_ENDPOINT = false;
 /**
+ * Don't delete this, used by older clients.
+ * @deprecated replaced by nodeFipsConfigSelectors in newer clients.
  * @internal
  */
 export declare const NODE_USE_FIPS_ENDPOINT_CONFIG_OPTIONS: LoadedConfigSelectors<boolean>;
+/**
+ * @internal
+ */
+export declare const nodeFipsConfigSelectors: LoadedConfigSelectors<boolean | undefined>;

package/node_modules/@smithy/config-resolver/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithy/config-resolver",
-  "version": "4.4.11",
+  "version": "4.4.13",
   "scripts": {
     "build": "concurrently 'yarn:build:cjs' 'yarn:build:es' 'yarn:build:types && yarn build:types:downlevel'",
     "build:cjs": "node ../../scripts/inline config-resolver",

package/node_modules/@smithy/middleware-endpoint/dist-types/resolveEndpointConfig.d.ts

@@ -31,11 +31,11 @@ export interface EndpointInputConfig<T extends EndpointParameters = EndpointPara
     /**
      * Enables IPv6/IPv4 dualstack endpoint.
      */
-    useDualstackEndpoint?: boolean | Provider<boolean>;
+    useDualstackEndpoint?: boolean | Provider<boolean | undefined>;
     /**
      * Enables FIPS compatible endpoints.
      */
-    useFipsEndpoint?: boolean | Provider<boolean>;
+    useFipsEndpoint?: boolean | Provider<boolean | undefined>;
     /**
      * @internal
      * This field is used internally so you should not fill any value to this field.

package/node_modules/@smithy/middleware-endpoint/dist-types/ts3.4/resolveEndpointConfig.d.ts

@@ -31,11 +31,11 @@ export interface EndpointInputConfig<T extends EndpointParameters = EndpointPara
     /**
      * Enables IPv6/IPv4 dualstack endpoint.
      */
-    useDualstackEndpoint?: boolean | Provider<boolean>;
+    useDualstackEndpoint?: boolean | Provider<boolean | undefined>;
     /**
      * Enables FIPS compatible endpoints.
      */
-    useFipsEndpoint?: boolean | Provider<boolean>;
+    useFipsEndpoint?: boolean | Provider<boolean | undefined>;
     /**
      * @internal
      * This field is used internally so you should not fill any value to this field.

package/node_modules/@smithy/middleware-endpoint/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithy/middleware-endpoint",
-  "version": "4.4.26",
+  "version": "4.4.27",
   "scripts": {
     "build": "concurrently 'yarn:build:cjs' 'yarn:build:es' 'yarn:build:types && yarn build:types:downlevel'",
     "build:cjs": "node ../../scripts/inline middleware-endpoint",

package/node_modules/@smithy/middleware-retry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithy/middleware-retry",
-  "version": "4.4.43",
+  "version": "4.4.44",
   "scripts": {
     "build": "concurrently 'yarn:build:cjs' 'yarn:build:es' 'yarn:build:types && yarn build:types:downlevel'",
     "build:cjs": "node ../../scripts/inline middleware-retry",
@@ -37,7 +37,7 @@
     "@smithy/node-config-provider": "^4.3.12",
     "@smithy/protocol-http": "^5.3.12",
     "@smithy/service-error-classification": "^4.2.12",
-    "@smithy/smithy-client": "^4.12.6",
+    "@smithy/smithy-client": "^4.12.7",
     "@smithy/types": "^4.13.1",
     "@smithy/util-middleware": "^4.2.12",
     "@smithy/util-retry": "^4.2.12",

package/node_modules/@smithy/smithy-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithy/smithy-client",
-  "version": "4.12.6",
+  "version": "4.12.7",
   "scripts": {
     "build": "concurrently 'yarn:build:cjs' 'yarn:build:es' 'yarn:build:types && yarn build:types:downlevel'",
     "build:cjs": "node ../../scripts/inline smithy-client",
@@ -28,7 +28,7 @@
   "sideEffects": false,
   "dependencies": {
     "@smithy/core": "^3.23.12",
-    "@smithy/middleware-endpoint": "^4.4.26",
+    "@smithy/middleware-endpoint": "^4.4.27",
     "@smithy/middleware-stack": "^4.2.12",
     "@smithy/protocol-http": "^5.3.12",
     "@smithy/types": "^4.13.1",

package/node_modules/@smithy/util-defaults-mode-browser/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithy/util-defaults-mode-browser",
-  "version": "4.3.42",
+  "version": "4.3.43",
   "scripts": {
     "build": "concurrently 'yarn:build:cjs' 'yarn:build:es' 'yarn:build:types && yarn build:types:downlevel'",
     "build:cjs": "node ../../scripts/inline util-defaults-mode-browser",
@@ -25,7 +25,7 @@
   "sideEffects": false,
   "dependencies": {
     "@smithy/property-provider": "^4.2.12",
-    "@smithy/smithy-client": "^4.12.6",
+    "@smithy/smithy-client": "^4.12.7",
     "@smithy/types": "^4.13.1",
     "tslib": "^2.6.2"
   },

package/node_modules/@smithy/util-defaults-mode-node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithy/util-defaults-mode-node",
-  "version": "4.2.45",
+  "version": "4.2.47",
   "scripts": {
     "build": "concurrently 'yarn:build:cjs' 'yarn:build:es' 'yarn:build:types && yarn build:types:downlevel'",
     "build:cjs": "node ../../scripts/inline util-defaults-mode-node",
@@ -24,11 +24,11 @@
   "license": "Apache-2.0",
   "sideEffects": false,
   "dependencies": {
-    "@smithy/config-resolver": "^4.4.11",
+    "@smithy/config-resolver": "^4.4.13",
     "@smithy/credential-provider-imds": "^4.2.12",
     "@smithy/node-config-provider": "^4.3.12",
     "@smithy/property-provider": "^4.2.12",
-    "@smithy/smithy-client": "^4.12.6",
+    "@smithy/smithy-client": "^4.12.7",
     "@smithy/types": "^4.13.1",
     "tslib": "^2.6.2"
   },

package/node_modules/path-expression-matcher/README.md

@@ -346,6 +346,57 @@ Restore from a snapshot.
 matcher.restore(snapshot);
 ```
 
+#### Read-Only Access
+
+##### `readOnly()`
+
+Returns a **live, read-only proxy** of the matcher. All query and inspection methods work normally, but any attempt to call a state-mutating method (`push`, `pop`, `reset`, `updateCurrent`, `restore`) or to write/delete a property throws a `TypeError`.
+
+This is the recommended way to share the matcher with external consumers — plugins, callbacks, event handlers — that only need to inspect the current path without being able to corrupt parser state.
+
+```javascript
+const ro = matcher.readOnly();
+```
+
+**What works on the read-only view:**
+
+```javascript
+ro.matches(expr)          // ✓ pattern matching
+ro.getCurrentTag()        // ✓ current tag name
+ro.getCurrentNamespace()  // ✓ current namespace
+ro.getAttrValue("id")     // ✓ attribute value
+ro.hasAttr("id")          // ✓ attribute presence check
+ro.getPosition()          // ✓ sibling position
+ro.getCounter()           // ✓ occurrence counter
+ro.getDepth()             // ✓ path depth
+ro.toString()             // ✓ path as string
+ro.toArray()              // ✓ path as array
+ro.snapshot()             // ✓ snapshot (can be used to restore the real matcher)
+```
+
+**What throws a `TypeError`:**
+
+```javascript
+ro.push("child", {})      // ✗ TypeError: Cannot call 'push' on a read-only Matcher
+ro.pop()                  // ✗ TypeError: Cannot call 'pop' on a read-only Matcher
+ro.reset()                // ✗ TypeError: Cannot call 'reset' on a read-only Matcher
+ro.updateCurrent({})      // ✗ TypeError: Cannot call 'updateCurrent' on a read-only Matcher
+ro.restore(snapshot)      // ✗ TypeError: Cannot call 'restore' on a read-only Matcher
+ro.separator = '/'        // ✗ TypeError: Cannot set property on a read-only Matcher
+```
+
+**Important:** The read-only view is **live** — it always reflects the current state of the underlying matcher. If you need a frozen-in-time copy instead, use `snapshot()`.
+
+```javascript
+const matcher = new Matcher();
+const ro = matcher.readOnly();
+
+matcher.push("root");
+ro.getDepth();    // 1 — immediately reflects the push
+matcher.push("users");
+ro.getDepth();    // 2 — still live
+```
+
 ## 💡 Usage Examples
 
 ### Example 1: XML Parser with stopNodes
@@ -481,7 +532,53 @@ const expr = new Expression("root.item:first");
 console.log(matcher.matches(expr)); // false (counter=1, not 0)
 ```
 
-### Example 7: Namespace Support (XML/SOAP)
+### Example 8: Passing a Read-Only Matcher to External Consumers
+
+When passing the matcher into callbacks, plugins, or other code you don't control, use `readOnly()` to prevent accidental state corruption.
+
+```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 a read-only view — consumer can inspect but not mutate
+  onTag(matcher.readOnly());
+
+  matcher.pop();
+}
+
+// Safe consumer — can only read
+function myPlugin(ro) {
+  if (ro.matches(adminExpr)) {
+    console.log("Admin at path:", ro.toString());
+    console.log("Depth:", ro.getDepth());
+    console.log("ID:", ro.getAttrValue("id"));
+  }
+}
+
+// ro.push(...) or ro.reset() here would throw TypeError,
+// so the parser's state is always safe.
+parseTag("user", { id: "1", type: "admin" }, myPlugin);
+```
+
+**Combining with `snapshot()`:** A snapshot taken via the read-only view can still be used to restore the real matcher.
+
+```javascript
+const matcher = new Matcher();
+matcher.push("root");
+matcher.push("users");
+
+const ro = matcher.readOnly();
+const snap = ro.snapshot();       // ✓ snapshot works on read-only view
+
+matcher.push("user");             // continue parsing...
+matcher.restore(snap);            // restore to "root.users" using the snapshot
+```
 
 ```javascript
 const matcher = new Matcher();
@@ -614,18 +711,6 @@ const parser = new XMLParser({
 });
 ```
 
-## 🧪 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