Merge pull request #9 from ajitpratap0/feature/phase-2-cte-implementation

feat: GoSQLX v1.2.0 - Phase 2: Complete CTE and Set Operations Implementation

Author: ajitpratap0

doc.go

@@ -1,8 +1,8 @@
 // Package gosqlx provides a high-performance SQL parsing SDK for Go with zero-copy tokenization
 // and object pooling. It offers production-ready SQL lexing, parsing, and AST generation with
-// support for multiple SQL dialects.
+// support for multiple SQL dialects and advanced SQL features.
 //
-// Features:
+// Core Features:
 //
 // - Zero-copy tokenization for optimal performance
 // - Object pooling for 60-80% memory reduction
@@ -12,6 +12,15 @@
 // - Performance monitoring and metrics collection
 // - Visitor pattern support for AST traversal
 //
+// Advanced SQL Features (Phase 2 - v1.2.0+):
+//
+// - Common Table Expressions (CTEs) with WITH clause
+// - Recursive CTEs with WITH RECURSIVE support
+// - Multiple CTEs in single query
+// - Set operations: UNION, UNION ALL, EXCEPT, INTERSECT
+// - Complex query compositions and left-associative parsing
+// - ~70% SQL-92 standards compliance
+//
 // Basic Usage:
 //
 //	import (
@@ -38,14 +47,40 @@
 //	}
 //	defer ast.ReleaseAST(astObj)
 //
+// Advanced Usage (Phase 2 Features):
+//
+//	// Common Table Expression (CTE)
+//	cteSQL := `WITH sales_summary AS (
+//	    SELECT region, SUM(amount) as total
+//	    FROM sales
+//	    GROUP BY region
+//	) SELECT region FROM sales_summary WHERE total > 1000`
+//
+//	// Recursive CTE
+//	recursiveSQL := `WITH RECURSIVE employee_tree AS (
+//	    SELECT employee_id, manager_id, name FROM employees WHERE manager_id IS NULL
+//	    UNION ALL
+//	    SELECT e.employee_id, e.manager_id, e.name
+//	    FROM employees e JOIN employee_tree et ON e.manager_id = et.employee_id
+//	) SELECT * FROM employee_tree`
+//
+//	// Set Operations
+//	unionSQL := `SELECT name FROM customers UNION SELECT name FROM suppliers`
+//	exceptSQL := `SELECT product FROM inventory EXCEPT SELECT product FROM discontinued`
+//	intersectSQL := `SELECT customer_id FROM orders INTERSECT SELECT customer_id FROM payments`
+//
 // Performance:
 //
 // GoSQLX achieves:
-// - 2.2M operations/second throughput
-// - 8M tokens/second processing speed
-// - <200ns latency for simple queries
-// - Linear scaling to 128 cores
-// - 60-80% memory reduction with pooling
+// - 946K+ sustained operations/second (30s load testing)
+// - 1.25M+ operations/second peak throughput (concurrent)
+// - 8M+ tokens/second processing speed
+// - <280ns latency for simple queries
+// - <1μs latency for complex queries with CTEs/set operations
+// - Linear scaling to 128+ cores
+// - 60-80% memory reduction with object pooling
+// - Zero memory leaks under extended load
+// - Race-free concurrent operation validated
 //
 // For more examples and detailed documentation, see:
 // https://github.com/ajitpratap0/GoSQLX

pkg/sql/ast/ast.go

@@ -1,5 +1,12 @@
 // Package ast provides Abstract Syntax Tree (AST) node definitions for SQL statements.
-// It includes support for DDL and DML operations with object pooling for performance optimization.
+// It includes comprehensive support for DDL and DML operations, Common Table Expressions (CTEs),
+// and set operations, with object pooling for performance optimization.
+//
+// Phase 2 Features (v1.2.0+):
+//   - WithClause and CommonTableExpr for CTE support
+//   - SetOperation for UNION, EXCEPT, INTERSECT operations
+//   - Recursive CTE support with proper AST representation
+//   - Integration with all statement types
 package ast
 
 import "fmt"
@@ -22,11 +29,9 @@ type Expression interface {
 	expressionNode()
 }
 
-// WithClause represents a WITH clause in a SQL statement
-// TODO: PHASE 2 - Complete CTE implementation
-// Current Status: AST structures defined, parser integration incomplete
-// Missing: parseWithClause, parseCommonTableExpr, parseStatementWithSetOps functions
-// Priority: High (Phase 2 core feature)
+// WithClause represents a WITH clause in a SQL statement.
+// It supports both simple and recursive Common Table Expressions (CTEs).
+// Phase 2 Complete: Full parser integration with all statement types.
 type WithClause struct {
 	Recursive bool
 	CTEs      []*CommonTableExpr
@@ -42,10 +47,9 @@ func (w WithClause) Children() []Node {
 	return children
 }
 
-// CommonTableExpr represents a single CTE in a WITH clause
-// TODO: PHASE 2 - Parser integration needed for CTE functionality
-// Current: AST structure complete, parser functions missing
-// Required: Integration with SELECT/INSERT/UPDATE/DELETE statement parsing
+// CommonTableExpr represents a single Common Table Expression in a WITH clause.
+// It supports optional column specifications and any statement type as the CTE query.
+// Phase 2 Complete: Full parser support with column specifications.
 type CommonTableExpr struct {
 	Name         string
 	Columns      []string
@@ -59,7 +63,9 @@ func (c CommonTableExpr) Children() []Node {
 	return []Node{c.Statement}
 }
 
-// SetOperation represents UNION, EXCEPT, INTERSECT operations
+// SetOperation represents set operations (UNION, EXCEPT, INTERSECT) between two statements.
+// It supports the ALL modifier (e.g., UNION ALL) and proper left-associative parsing.
+// Phase 2 Complete: Full parser support with left-associative precedence.
 type SetOperation struct {
 	Left     Statement
 	Operator string // UNION, EXCEPT, INTERSECT