feat: Parser Enhancements Batch 5 - ARRAY Constructor, WITHIN GROUP & JSONB Operators (#187)

Implements three new parser features:

## Issue #178: PostgreSQL JSONB Existence Operators
- Fixed token converter to properly handle ?, ?|, ?& operators
- These were incorrectly being converted to placeholder tokens
- Added proper type mappings in buildTypeMapping()

## Issue #182: PostgreSQL ARRAY Constructor Syntax
- Added TokenTypeArray (395) and TokenTypeWithin (396) token types
- Added ARRAY and WITHIN keywords to keywords.go and tokenizer.go
- Added ArrayConstructorExpression AST node with pooling
- Supports both ARRAY[...] literal and ARRAY(SELECT...) subquery syntax
- Added parseArrayConstructor() function in expressions.go

## Issue #183: SQL:2003 WITHIN GROUP Ordered-Set Aggregates
- Added WithinGroup field to FunctionCall struct
- Added parsing support in window.go parseFunctionCall()
- Supports PERCENTILE_CONT, PERCENTILE_DISC, MODE, LISTAGG
- Includes ASC/DESC and NULLS FIRST/LAST ordering

Test Coverage:
- Added array_constructor_test.go with 15+ test cases
- Added within_group_test.go with 12+ test cases
- Added json_operators_test.go parser tests
- All 26 packages pass with race detection

Closes #178, #182, #183

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Ajit Pratap Singh <ajitpratapsingh@Ajits-Mac-mini.local>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: 3 people

cmd/gosqlx/cmd/sql_formatter.go

@@ -256,9 +256,14 @@ func (f *SQLFormatter) formatInsert(stmt *ast.InsertStatement) error {
 	if len(stmt.Values) > 0 {
 		f.writeNewline()
 		f.writeKeyword("VALUES")
-		f.builder.WriteString(" (")
-		f.formatExpressionList(stmt.Values, ", ")
-		f.builder.WriteString(")")
+		for i, row := range stmt.Values {
+			if i > 0 {
+				f.builder.WriteString(",")
+			}
+			f.builder.WriteString(" (")
+			f.formatExpressionList(row, ", ")
+			f.builder.WriteString(")")
+		}
 	}
 
 	if stmt.Query != nil {

pkg/gosqlx/extract.go

@@ -928,8 +928,10 @@ func (fc *functionCollector) collectFromNode(node ast.Node) {
 			fc.collectFromNode(n.With)
 		}
 	case *ast.InsertStatement:
-		for _, val := range n.Values {
-			fc.collectFromExpression(val)
+		for _, row := range n.Values {
+			for _, val := range row {
+				fc.collectFromExpression(val)
+			}
 		}
 		if n.Query != nil {
 			fc.collectFromNode(n.Query)

pkg/models/token_type.go

@@ -337,6 +337,8 @@ const (
 	TokenTypeCube         TokenType = 392
 	TokenTypeGrouping     TokenType = 393
 	TokenTypeSets         TokenType = 394 // SETS keyword for GROUPING SETS
+	TokenTypeArray        TokenType = 395 // ARRAY keyword for PostgreSQL array constructor
+	TokenTypeWithin       TokenType = 396 // WITHIN keyword for WITHIN GROUP clause
 
 	// Role/Permission Keywords (400-419)
 	TokenTypeRole       TokenType = 400
@@ -620,6 +622,8 @@ var tokenStringMap = map[TokenType]string{
 	TokenTypeCube:         "CUBE",
 	TokenTypeGrouping:     "GROUPING",
 	TokenTypeSets:         "SETS",
+	TokenTypeArray:        "ARRAY",
+	TokenTypeWithin:       "WITHIN",
 
 	// Role/Permission Keywords
 	TokenTypeRole:       "ROLE",

pkg/sql/ast/ast.go

@@ -602,13 +602,15 @@ func (i Identifier) Children() []Node     { return nil }
 // New in v1.6.0:
 //   - Filter: FILTER clause for conditional aggregation
 //   - OrderBy: ORDER BY clause for order-sensitive aggregates (STRING_AGG, ARRAY_AGG, etc.)
+//   - WithinGroup: ORDER BY clause for ordered-set aggregates (PERCENTILE_CONT, PERCENTILE_DISC, MODE, etc.)
 type FunctionCall struct {
-	Name      string
-	Arguments []Expression // Renamed from Args for consistency
-	Over      *WindowSpec  // For window functions
-	Distinct  bool
-	Filter    Expression          // WHERE clause for aggregate functions
-	OrderBy   []OrderByExpression // ORDER BY clause for aggregate functions (STRING_AGG, ARRAY_AGG, etc.)
+	Name        string
+	Arguments   []Expression // Renamed from Args for consistency
+	Over        *WindowSpec  // For window functions
+	Distinct    bool
+	Filter      Expression          // WHERE clause for aggregate functions
+	OrderBy     []OrderByExpression // ORDER BY clause for aggregate functions (STRING_AGG, ARRAY_AGG, etc.)
+	WithinGroup []OrderByExpression // ORDER BY clause for ordered-set aggregates (PERCENTILE_CONT, etc.)
 }
 
 func (f *FunctionCall) expressionNode()     {}
@@ -625,6 +627,10 @@ func (f FunctionCall) Children() []Node {
 		orderBy := orderBy // G601: Create local copy to avoid memory aliasing
 		children = append(children, &orderBy)
 	}
+	for _, orderBy := range f.WithinGroup {
+		orderBy := orderBy // G601: Create local copy to avoid memory aliasing
+		children = append(children, &orderBy)
+	}
 	return children
 }
 
@@ -887,6 +893,38 @@ func (l *ListExpression) expressionNode()     {}
 func (l ListExpression) TokenLiteral() string { return "LIST" }
 func (l ListExpression) Children() []Node     { return nodifyExpressions(l.Values) }
 
+// TupleExpression represents a row constructor / tuple (col1, col2) for multi-column comparisons
+// Used in: WHERE (user_id, status) IN ((1, 'active'), (2, 'pending'))
+type TupleExpression struct {
+	Expressions []Expression
+}
+
+func (t *TupleExpression) expressionNode()     {}
+func (t TupleExpression) TokenLiteral() string { return "TUPLE" }
+func (t TupleExpression) Children() []Node     { return nodifyExpressions(t.Expressions) }
+
+// ArrayConstructorExpression represents PostgreSQL ARRAY constructor syntax.
+// Creates an array value from a list of expressions or a subquery.
+//
+// Examples:
+//
+//	ARRAY[1, 2, 3]                    - Integer array literal
+//	ARRAY['admin', 'moderator']      - Text array literal
+//	ARRAY(SELECT id FROM users)      - Array from subquery
+type ArrayConstructorExpression struct {
+	Elements []Expression     // Elements inside ARRAY[...]
+	Subquery *SelectStatement // For ARRAY(SELECT ...) syntax (optional)
+}
+
+func (a *ArrayConstructorExpression) expressionNode()     {}
+func (a ArrayConstructorExpression) TokenLiteral() string { return "ARRAY" }
+func (a ArrayConstructorExpression) Children() []Node {
+	if a.Subquery != nil {
+		return []Node{a.Subquery}
+	}
+	return nodifyExpressions(a.Elements)
+}
+
 // UnaryExpression represents operations like NOT expr
 type UnaryExpression struct {
 	Operator UnaryOperator
@@ -963,7 +1001,7 @@ type InsertStatement struct {
 	With       *WithClause
 	TableName  string
 	Columns    []Expression
-	Values     []Expression
+	Values     [][]Expression   // Multi-row support: each inner slice is one row of values
 	Query      *SelectStatement // For INSERT ... SELECT
 	Returning  []Expression
 	OnConflict *OnConflict
@@ -978,7 +1016,10 @@ func (i InsertStatement) Children() []Node {
 		children = append(children, i.With)
 	}
 	children = append(children, nodifyExpressions(i.Columns)...)
-	children = append(children, nodifyExpressions(i.Values)...)
+	// Flatten multi-row values for Children()
+	for _, row := range i.Values {
+		children = append(children, nodifyExpressions(row)...)
+	}
 	if i.Query != nil {
 		children = append(children, i.Query)
 	}

pkg/sql/ast/coverage_test.go

@@ -298,10 +298,10 @@ func TestSpanMethods(t *testing.T) {
 				&Identifier{Name: "id"},
 				&Identifier{Name: "name"},
 			},
-			Values: []Expression{
+			Values: [][]Expression{{
 				&LiteralValue{Value: 1},
 				&LiteralValue{Value: "test"},
-			},
+			}},
 		}
 		span := insert.Span()
 		// Should return combined span of components
@@ -830,7 +830,7 @@ func TestInsertStatementChildrenCoverage(t *testing.T) {
 			},
 			TableName: "users",
 			Columns:   []Expression{&Identifier{Name: "id"}},
-			Values:    []Expression{&LiteralValue{Value: 1}},
+			Values:    [][]Expression{{&LiteralValue{Value: 1}}},
 			Query:     &SelectStatement{},
 			Returning: []Expression{&Identifier{Name: "id"}},
 			OnConflict: &OnConflict{

pkg/sql/ast/interface_test.go

@@ -799,7 +799,7 @@ func TestInsertStatementChildren(t *testing.T) {
 		stmt := &InsertStatement{
 			With:       &WithClause{},
 			Columns:    []Expression{testIdent},
-			Values:     []Expression{testExpr},
+			Values:     [][]Expression{{testExpr}},
 			Query:      &SelectStatement{},
 			Returning:  []Expression{testIdent},
 			OnConflict: &OnConflict{},

pkg/sql/ast/nodes_test.go

@@ -539,7 +539,7 @@ func TestInsertStatement(t *testing.T) {
 			stmt: &InsertStatement{
 				TableName: "users",
 				Columns:   []Expression{&Identifier{Name: "name"}, &Identifier{Name: "email"}},
-				Values:    []Expression{&LiteralValue{Value: "John"}, &LiteralValue{Value: "john@example.com"}},
+				Values:    [][]Expression{{&LiteralValue{Value: "John"}, &LiteralValue{Value: "john@example.com"}}},
 			},
 			wantLiteral: "INSERT",
 			minChildren: 2,

pkg/sql/ast/pool.go

@@ -53,7 +53,7 @@ var (
 		New: func() interface{} {
 			return &InsertStatement{
 				Columns: make([]Expression, 0, 4),
-				Values:  make([]Expression, 0, 4),
+				Values:  make([][]Expression, 0, 4),
 			}
 		},
 	}
@@ -129,6 +129,22 @@ var (
 		},
 	}
 
+	tupleExprPool = sync.Pool{
+		New: func() interface{} {
+			return &TupleExpression{
+				Expressions: make([]Expression, 0, 4),
+			}
+		},
+	}
+
+	arrayConstructorPool = sync.Pool{
+		New: func() interface{} {
+			return &ArrayConstructorExpression{
+				Elements: make([]Expression, 0, 4),
+			}
+		},
+	}
+
 	subqueryExprPool = sync.Pool{
 		New: func() interface{} {
 			return &SubqueryExpression{}
@@ -337,9 +353,13 @@ func PutInsertStatement(stmt *InsertStatement) {
 		PutExpression(stmt.Columns[i])
 		stmt.Columns[i] = nil
 	}
+	// Clean up multi-row values
 	for i := range stmt.Values {
-		PutExpression(stmt.Values[i])
-		stmt.Values[i] = nil
+		for j := range stmt.Values[i] {
+			PutExpression(stmt.Values[i][j])
+			stmt.Values[i][j] = nil
+		}
+		stmt.Values[i] = stmt.Values[i][:0]
 	}
 
 	// Reset slices but keep capacity
@@ -784,6 +804,27 @@ func PutExpression(expr Expression) {
 			e.Values = e.Values[:0]
 			listExprPool.Put(e)
 
+		case *TupleExpression:
+			for i := range e.Expressions {
+				if e.Expressions[i] != nil {
+					workQueue = append(workQueue, e.Expressions[i])
+				}
+				e.Expressions[i] = nil
+			}
+			e.Expressions = e.Expressions[:0]
+			tupleExprPool.Put(e)
+
+		case *ArrayConstructorExpression:
+			for i := range e.Elements {
+				if e.Elements[i] != nil {
+					workQueue = append(workQueue, e.Elements[i])
+				}
+				e.Elements[i] = nil
+			}
+			e.Elements = e.Elements[:0]
+			e.Subquery = nil
+			arrayConstructorPool.Put(e)
+
 		case *UnaryExpression:
 			if e.Expr != nil {
 				workQueue = append(workQueue, e.Expr)
@@ -933,6 +974,48 @@ func PutInExpression(ie *InExpression) {
 	inExprPool.Put(ie)
 }
 
+// GetTupleExpression gets a TupleExpression from the pool
+func GetTupleExpression() *TupleExpression {
+	te := tupleExprPool.Get().(*TupleExpression)
+	te.Expressions = te.Expressions[:0]
+	return te
+}
+
+// PutTupleExpression returns a TupleExpression to the pool
+func PutTupleExpression(te *TupleExpression) {
+	if te == nil {
+		return
+	}
+	for i := range te.Expressions {
+		PutExpression(te.Expressions[i])
+		te.Expressions[i] = nil
+	}
+	te.Expressions = te.Expressions[:0]
+	tupleExprPool.Put(te)
+}
+
+// GetArrayConstructor gets an ArrayConstructorExpression from the pool
+func GetArrayConstructor() *ArrayConstructorExpression {
+	ac := arrayConstructorPool.Get().(*ArrayConstructorExpression)
+	ac.Elements = ac.Elements[:0]
+	ac.Subquery = nil
+	return ac
+}
+
+// PutArrayConstructor returns an ArrayConstructorExpression to the pool
+func PutArrayConstructor(ac *ArrayConstructorExpression) {
+	if ac == nil {
+		return
+	}
+	for i := range ac.Elements {
+		PutExpression(ac.Elements[i])
+		ac.Elements[i] = nil
+	}
+	ac.Elements = ac.Elements[:0]
+	ac.Subquery = nil
+	arrayConstructorPool.Put(ac)
+}
+
 // GetSubqueryExpression gets a SubqueryExpression from the pool
 func GetSubqueryExpression() *SubqueryExpression {
 	return subqueryExprPool.Get().(*SubqueryExpression)

pkg/sql/ast/pool_test.go

@@ -21,9 +21,12 @@ func TestInsertStatementPool(t *testing.T) {
 			&Identifier{Name: "name"},
 			&Identifier{Name: "email"},
 		}
-		stmt.Values = []Expression{
-			&LiteralValue{Value: "John"},
-			&LiteralValue{Value: "john@example.com"},
+		// Values is now [][]Expression for multi-row support
+		stmt.Values = [][]Expression{
+			{
+				&LiteralValue{Value: "John"},
+				&LiteralValue{Value: "john@example.com"},
+			},
 		}
 
 		// Return to pool
@@ -371,7 +374,8 @@ func TestMemoryLeaks_InsertStatementPool(t *testing.T) {
 
 		stmt.TableName = "users"
 		stmt.Columns = append(stmt.Columns, &Identifier{Name: "name"}, &Identifier{Name: "email"})
-		stmt.Values = append(stmt.Values, &LiteralValue{Value: "John"}, &LiteralValue{Value: "john@test.com"})
+		// Values is now [][]Expression for multi-row support
+		stmt.Values = append(stmt.Values, []Expression{&LiteralValue{Value: "John"}, &LiteralValue{Value: "john@test.com"}})
 
 		PutInsertStatement(stmt)
 

pkg/sql/ast/span.go

@@ -96,9 +96,11 @@ func (i *InsertStatement) Span() models.Span {
 		}
 	}
 
-	for _, val := range i.Values {
-		if spanned, ok := val.(Spanned); ok {
-			spans = append(spans, spanned.Span())
+	for _, row := range i.Values {
+		for _, val := range row {
+			if spanned, ok := val.(Spanned); ok {
+				spans = append(spans, spanned.Span())
+			}
 		}
 	}