Optimize lazy context tracking and descendant traversal performance

README.md

@@ -62,6 +62,7 @@ store:
 ### Context Variables
 
 Context variables provide information about the current evaluation context within filter expressions. They are prefixed with `@` and can be used in comparisons.
+By default, context tracking is eager to preserve historical behavior. If you want to reduce overhead for queries that do not use context variables, enable `config.WithLazyContextTracking()` to turn on tracking only when a query uses `@property`, `@path`, `@parentProperty`, or `@index`.
 
 #### `@property`
 

go.sum

@@ -12,8 +12,6 @@ github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZV
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
-go.yaml.in/yaml/v4 v4.0.0-rc.2 h1:/FrI8D64VSr4HtGIlUtlFMGsm7H7pWTbj6vOLVZcA6s=
-go.yaml.in/yaml/v4 v4.0.0-rc.2/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
 go.yaml.in/yaml/v4 v4.0.0-rc.4 h1:UP4+v6fFrBIb1l934bDl//mmnoIZEDK0idg1+AIvX5U=
 go.yaml.in/yaml/v4 v4.0.0-rc.4/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

pkg/jsonpath/config/config.go

@@ -10,6 +10,15 @@ func WithPropertyNameExtension() Option {
 	}
 }
 
+// WithLazyContextTracking enables on-demand tracking for JSONPath Plus context variables.
+// When enabled, tracking is only turned on if the query uses @property, @path, @parentProperty, or @index.
+// Defaults to false to preserve historical eager tracking behavior.
+func WithLazyContextTracking() Option {
+	return func(cfg *config) {
+		cfg.lazyContextTracking = true
+	}
+}
+
 // WithStrictRFC9535 disables JSONPath Plus extensions and enforces strict RFC 9535 compliance.
 // By default, JSONPath Plus extensions are enabled as they are a true superset of RFC 9535.
 // Use this option if you need to ensure pure RFC 9535 compliance.
@@ -22,11 +31,13 @@ func WithStrictRFC9535() Option {
 type Config interface {
 	PropertyNameEnabled() bool
 	JSONPathPlusEnabled() bool
+	LazyContextTrackingEnabled() bool
 }
 
 type config struct {
 	propertyNameExtension bool
 	strictRFC9535         bool
+	lazyContextTracking   bool
 }
 
 func (c *config) PropertyNameEnabled() bool {
@@ -40,6 +51,12 @@ func (c *config) JSONPathPlusEnabled() bool {
 	return !c.strictRFC9535
 }
 
+// LazyContextTrackingEnabled returns true if on-demand tracking is enabled.
+// Defaults to false for backward compatibility.
+func (c *config) LazyContextTrackingEnabled() bool {
+	return c.lazyContextTracking
+}
+
 func New(opts ...Option) Config {
 	cfg := &config{}
 	for _, opt := range opts {

pkg/jsonpath/config/config_test.go

@@ -0,0 +1,15 @@
+package config
+
+import "testing"
+
+func TestLazyContextTrackingOption(t *testing.T) {
+	cfg := New()
+	if cfg.LazyContextTrackingEnabled() {
+		t.Fatalf("expected lazy context tracking disabled by default")
+	}
+
+	cfg = New(WithLazyContextTracking())
+	if !cfg.LazyContextTrackingEnabled() {
+		t.Fatalf("expected lazy context tracking enabled with option")
+	}
+}