feat: add some utility functions and document reduce better (#99)

Author: steve-r-west

README.md

@@ -148,9 +148,89 @@ Over time this value and argument might change as we get more experience, in the
 
 Regular Expressions can also be set when using the Validation functions, the same rules apply as for aliases (see above). In general aliases are resolved prior to validation rules and operator checks.
 
+### Working with ASTs
+
+#### Reduce & Semantic Reduce
+
+The library provides two approaches for processing AST trees: `ReduceAst()` and `SemanticReduceAst()`.
+
+##### ReduceAst()
+
+`ReduceAst()` is a low-level generic function that recursively processes an AST tree. It's useful when you need to process all nodes uniformly, regardless of their operator type. For example, extracting all field names, calculating tree depth, or transforming field names.
+
+```go
+// Example: Collect all field names from the AST
+result, _ := epsearchast_v3.ReduceAst(ast, func(node *epsearchast_v3.AstNode, children []*[]string) (*[]string, error) {
+	fields := []string{}
+	if len(node.Args) > 0 {
+		fields = append(fields, node.Args[0])
+	}
+	for _, child := range children {
+		if child != nil {
+			fields = append(fields, *child...)
+		}
+	}
+	return &fields, nil
+})
+```
+
+##### SemanticReduceAst()
+
+`SemanticReduceAst()` is a higher-level wrapper that uses the `SemanticReducer` interface to provide individual methods for each operator type (VisitEq, VisitLt, etc.). This is the recommended approach for generating queries, as each operator can be translated differently.
+
+```go
+// Example: Generate a SQL query using GORM
+var qb epsearchast_v3.SemanticReducer[epsearchast_v3_gorm.SubQuery] = epsearchast_v3_gorm.DefaultGormQueryBuilder{}
+sq, err := epsearchast_v3.SemanticReduceAst(ast, qb)
+```
+
+**When to use which:**
+- Use `ReduceAst()` when you care about the tree structure but not the specific operators (e.g., collecting field names, calculating depth, transforming field names)
+- Use `SemanticReduceAst()` when you need operator-specific behavior (e.g., generating database queries where EQ, LT, GE each translate differently)
+
 #### Customizing ASTs
 
-You can use the `IdentitySemanticReducer` type to simplify rewriting ASTs, by embedding this struct you can only override and process the specific parts you care about. Post processing the AST tree might be simplier than trying to post process a query written in your langauge, or while rebuilding a query.
+You can use the `IdentitySemanticReducer` type to simplify rewriting ASTs, by embedding this struct you can only override and process the specific parts you care about. Post-processing the AST tree might be simplier than trying to post process a query written in your langauge, or while rebuilding a query.
+
+#### Util Functions
+
+The library provides several utility functions for working with ASTs:
+
+##### GetAllFirstArgs()/GetAllFirstArgsSorted()/GetAllFirstUnique()
+
+Returns all first arguments (field names) from the AST. Useful for permission checking, index optimization, or field validation.
+
+```go
+fields := epsearchast_v3.GetAllFirstArgs(ast)           // []string{"status", "amount", "status"} - includes duplicates
+sortedFields := epsearchast_v3.GetAllFirstArgsSorted(ast)  // []string{"amount", "status", "status"} - sorted
+uniqueFields := epsearchast_v3.GetAllFirstArgsUnique(ast)  // map[string]struct{}{"status": {}, "amount": {}}
+```
+
+##### HasFirstArg()
+
+Returns true if a specific field name appears anywhere in the AST. Useful for quickly checking if a field is referenced before performing expensive operations.
+
+```go
+hasStatus := epsearchast_v3.HasFirstArg(ast, "status")  // true if "status" appears as a field name anywhere in the query
+```
+
+##### GetAstDepth()
+
+Returns the maximum depth of the AST tree. Useful for limiting query complexity.
+
+```go
+depth := epsearchast_v3.GetAstDepth(ast)
+```
+
+##### GetEffectiveIndexIntersectionCount()
+
+Returns a heuristic measure of query complexity based on potential index intersections. Used internally to cap OR query complexity (default limit is 4). See the "OR Filter Restrictions" section for more details.
+
+```go
+count, err := epsearchast_v3.GetEffectiveIndexIntersectionCount(ast)
+```
+
+
 
 ### Generating Queries
 

external/epsearchast/v3/util.go

@@ -1,6 +1,9 @@
 package epsearchast_v3
 
-import "fmt"
+import (
+	"fmt"
+	"sort"
+)
 
 func GetAstDepth(a *AstNode) int {
 	if a == nil {
@@ -113,3 +116,80 @@ func (e effectiveIndexIntersectionCount) VisitIsNull(first string) (*uint64, err
 func ptr(i uint64) (*uint64, error) {
 	return &i, nil
 }
+
+// GetAllFirstArgs returns all first arguments from the AST nodes.
+// For operators like EQ, LT, GE, etc., this returns the field name being queried.
+// For operators with multiple arguments like IN or CONTAINS_ANY, only the first argument (the field name) is returned.
+// Duplicate field names are included in the result.
+func GetAllFirstArgs(a *AstNode) []string {
+	result, _ := ReduceAst(a, func(node *AstNode, children []*[]string) (*[]string, error) {
+		fields := []string{}
+
+		// Collect the first arg from this node (if it has args)
+		if len(node.Args) > 0 {
+			fields = append(fields, node.Args[0])
+		}
+
+		// Merge results from all children
+		for _, child := range children {
+			if child != nil {
+				fields = append(fields, *child...)
+			}
+		}
+
+		return &fields, nil
+	})
+
+	if result == nil {
+		return []string{}
+	}
+	return *result
+}
+
+// GetAllFirstArgsSorted returns all first arguments from the AST nodes in sorted order.
+// This is a convenience function that calls GetAllFirstArgs and sorts the result.
+// Duplicate field names are included in the result.
+func GetAllFirstArgsSorted(a *AstNode) []string {
+	fields := GetAllFirstArgs(a)
+	sort.Strings(fields)
+	return fields
+}
+
+// GetAllFirstArgsUnique returns a set of unique first arguments from the AST nodes.
+// This is a convenience function that calls GetAllFirstArgs and builds a unique set.
+func GetAllFirstArgsUnique(a *AstNode) map[string]struct{} {
+	fields := GetAllFirstArgs(a)
+	unique := make(map[string]struct{}, len(fields))
+	for _, field := range fields {
+		unique[field] = struct{}{}
+	}
+	return unique
+}
+
+// HasFirstArg returns true if the specified field name appears as a first argument anywhere in the AST.
+// This is useful for quickly checking if a specific field is referenced in the query.
+func HasFirstArg(a *AstNode, fieldName string) bool {
+	result, _ := ReduceAst(a, func(node *AstNode, children []*bool) (*bool, error) {
+		// Check if this node has the field we're looking for
+		if len(node.Args) > 0 && node.Args[0] == fieldName {
+			found := true
+			return &found, nil
+		}
+
+		// Check if any children found it
+		for _, child := range children {
+			if child != nil && *child {
+				found := true
+				return &found, nil
+			}
+		}
+
+		notFound := false
+		return &notFound, nil
+	})
+
+	if result == nil {
+		return false
+	}
+	return *result
+}