refactor: remove collectors from ParsedQuery

Author: norberttech

documentation/components/libs/pg-query.md

@@ -21,27 +21,27 @@ composer require flow-php/pg-query:~--FLOW_PHP_VERSION--
 ```php
 <?php
 
-use function Flow\PgQuery\DSL\pg_parse;
+use function Flow\PgQuery\DSL\{pg_parse, pg_query_tables, pg_query_columns, pg_query_functions};
 
 $query = pg_parse('SELECT u.id, u.name FROM users u JOIN orders o ON u.id = o.user_id');
 
 // Get all tables
-foreach ($query->tables() as $table) {
+foreach (pg_query_tables($query)->all() as $table) {
     echo $table->name();  // 'users', 'orders'
     echo $table->alias(); // 'u', 'o'
 }
 
 // Get all columns
-foreach ($query->columns() as $column) {
+foreach (pg_query_columns($query)->all() as $column) {
     echo $column->name();  // 'id', 'name', 'id', 'user_id'
     echo $column->table(); // 'u', 'u', 'u', 'o'
 }
 
 // Get columns for specific table
-$userColumns = $query->columns('u');
+$userColumns = pg_query_columns($query)->forTable('u');
 
 // Get all function calls
-foreach ($query->functions() as $func) {
+foreach (pg_query_functions($query)->all() as $func) {
     echo $func->name();   // function name
     echo $func->schema(); // schema if qualified (e.g., 'pg_catalog')
 }
@@ -97,6 +97,9 @@ use function Flow\PgQuery\DSL\{
     pg_deparse_options,
     pg_format,
     pg_summary,
+    pg_query_columns,
+    pg_query_tables,
+    pg_query_functions,
     pg_to_paginated_query,
     pg_to_count_query,
     pg_to_keyset_query,
@@ -111,6 +114,11 @@ $normalizedDdl = pg_normalize_utility('CREATE TABLE users (id INT)');
 $statements = pg_split('SELECT 1; SELECT 2;');
 $summary = pg_summary('SELECT * FROM users');
 
+// Extract columns, tables, and functions
+$columns = pg_query_columns($query)->all();
+$tables = pg_query_tables($query)->all();
+$functions = pg_query_functions(pg_parse('SELECT COUNT(*) FROM users'))->all();
+
 // Deparse (convert AST back to SQL)
 $sql = pg_deparse($query);  // Simple output
 $sql = pg_deparse($query, pg_deparse_options()->indentSize(2));  // Pretty printed
@@ -127,13 +135,30 @@ $formatted = pg_format('SELECT id,name FROM users WHERE active=true');
 
 | Method | Description | Returns |
 |--------|-------------|---------|
-| `tables()` | Get all tables referenced in the query | `array<Table>` |
-| `columns(?string $tableName)` | Get columns, optionally filtered by table/alias | `array<Column>` |
-| `functions()` | Get all function calls | `array<FunctionCall>` |
 | `deparse(?DeparseOptions $options)` | Convert AST back to SQL string | `string` |
 | `traverse(NodeVisitor|NodeModifier ...)` | Traverse AST with visitors/modifiers | `$this` |
 | `raw()` | Access underlying protobuf ParseResult | `ParseResult` |
 
+## Extractor Functions
+
+| Function | Description | Returns |
+|----------|-------------|---------|
+| `pg_query_tables($query)` | Extract tables from the query | `Tables` |
+| `pg_query_columns($query)` | Extract columns from the query | `Columns` |
+| `pg_query_functions($query)` | Extract function calls from the query | `Functions` |
+
+### Extractor Methods
+
+**Columns** extractor:
+- `all()` - Get all columns
+- `forTable(string $tableName)` - Get columns filtered by table/alias
+
+**Tables** extractor:
+- `all()` - Get all tables
+
+**Functions** extractor:
+- `all()` - Get all function calls
+
 ## Deparsing (AST to SQL)
 
 Convert a parsed query back to SQL, optionally with pretty-printing:

src/lib/pg-query/src/Flow/PgQuery/DSL/functions.php

@@ -7,6 +7,7 @@
 use Flow\ETL\Attribute\{DocumentationDSL, Module, Type as DSLType};
 use Flow\PgQuery\AST\Transformers\{CountModifier, KeysetColumn, KeysetPaginationConfig, KeysetPaginationModifier, PaginationConfig, PaginationModifier, SortOrder};
 use Flow\PgQuery\{DeparseOptions, ParsedQuery, Parser};
+use Flow\PgQuery\Extractors\{Columns, Functions, Tables};
 
 #[DocumentationDSL(module: Module::PG_QUERY, type: DSLType::HELPER)]
 function pg_parser() : Parser
@@ -247,3 +248,30 @@ function pg_keyset_pagination(int $limit, array $columns, ?array $cursor = null)
 {
     return new KeysetPaginationModifier(new KeysetPaginationConfig($limit, $columns, $cursor));
 }
+
+/**
+ * Extract columns from a parsed SQL query.
+ */
+#[DocumentationDSL(module: Module::PG_QUERY, type: DSLType::HELPER)]
+function pg_query_columns(ParsedQuery $query) : Columns
+{
+    return new Columns($query);
+}
+
+/**
+ * Extract tables from a parsed SQL query.
+ */
+#[DocumentationDSL(module: Module::PG_QUERY, type: DSLType::HELPER)]
+function pg_query_tables(ParsedQuery $query) : Tables
+{
+    return new Tables($query);
+}
+
+/**
+ * Extract functions from a parsed SQL query.
+ */
+#[DocumentationDSL(module: Module::PG_QUERY, type: DSLType::HELPER)]
+function pg_query_functions(ParsedQuery $query) : Functions
+{
+    return new Functions($query);
+}

src/lib/pg-query/src/Flow/PgQuery/Extractors/Columns.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\PgQuery\Extractors;
+
+use Flow\PgQuery\AST\Nodes\Column;
+use Flow\PgQuery\AST\Visitors\ColumnRefCollector;
+use Flow\PgQuery\ParsedQuery;
+
+final readonly class Columns
+{
+    public function __construct(private ParsedQuery $query)
+    {
+    }
+
+    /**
+     * @return array<Column>
+     */
+    public function all() : array
+    {
+        $collector = new ColumnRefCollector();
+        $this->query->traverse($collector);
+
+        return \array_values(\array_filter(
+            \array_map(static fn ($ref) => new Column($ref), $collector->getColumnRefs()),
+            static fn ($col) => $col->name() !== null
+        ));
+    }
+
+    /**
+     * @return array<Column>
+     */
+    public function forTable(string $tableName) : array
+    {
+        return \array_values(\array_filter(
+            $this->all(),
+            static fn ($col) => $col->table() === $tableName
+        ));
+    }
+}

src/lib/pg-query/src/Flow/PgQuery/Extractors/Functions.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\PgQuery\Extractors;
+
+use Flow\PgQuery\AST\Nodes\FunctionCall;
+use Flow\PgQuery\AST\Visitors\FuncCallCollector;
+use Flow\PgQuery\ParsedQuery;
+
+final readonly class Functions
+{
+    public function __construct(private ParsedQuery $query)
+    {
+    }
+
+    /**
+     * @return array<FunctionCall>
+     */
+    public function all() : array
+    {
+        $collector = new FuncCallCollector();
+        $this->query->traverse($collector);
+
+        return \array_values(\array_filter(
+            \array_map(static fn ($ref) => new FunctionCall($ref), $collector->getFuncCalls()),
+            static fn ($func) => $func->name() !== null
+        ));
+    }
+}

src/lib/pg-query/src/Flow/PgQuery/Extractors/Tables.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\PgQuery\Extractors;
+
+use Flow\PgQuery\AST\Nodes\Table;
+use Flow\PgQuery\AST\Visitors\RangeVarCollector;
+use Flow\PgQuery\ParsedQuery;
+
+final readonly class Tables
+{
+    public function __construct(private ParsedQuery $query)
+    {
+    }
+
+    /**
+     * @return array<Table>
+     */
+    public function all() : array
+    {
+        $collector = new RangeVarCollector();
+        $this->query->traverse($collector);
+
+        return \array_values(\array_filter(
+            \array_map(static fn ($ref) => new Table($ref), $collector->getRangeVars()),
+            static fn ($table) => $table->name() !== ''
+        ));
+    }
+}

src/lib/pg-query/src/Flow/PgQuery/ParsedQuery.php

@@ -5,8 +5,6 @@
 namespace Flow\PgQuery;
 
 use Flow\PgQuery\AST\{NodeModifier, NodeVisitor, Traverser};
-use Flow\PgQuery\AST\Nodes\{Column, FunctionCall, Table};
-use Flow\PgQuery\AST\Visitors\{ColumnRefCollector, FuncCallCollector, RangeVarCollector};
 use Flow\PgQuery\Protobuf\AST\ParseResult;
 
 final readonly class ParsedQuery
@@ -16,34 +14,6 @@ public function __construct(
     ) {
     }
 
-    /**
-     * @return array<Column>
-     */
-    public function columns(?string $tableName = null) : array
-    {
-        $collector = new ColumnRefCollector();
-        $traverser = new Traverser($collector);
-        $traverser->traverse($this->parseResult);
-
-        $columns = [];
-
-        foreach ($collector->getColumnRefs() as $columnRef) {
-            $column = new Column($columnRef);
-
-            if ($column->name() === null) {
-                continue;
-            }
-
-            if ($tableName !== null && $column->table() !== $tableName) {
-                continue;
-            }
-
-            $columns[] = $column;
-        }
-
-        return $columns;
-    }
-
     /**
      * Convert the parsed AST back to SQL string.
      *
@@ -68,59 +38,11 @@ public function deparse(?DeparseOptions $options = null) : string
         );
     }
 
-    /**
-     * @return array<FunctionCall>
-     */
-    public function functions() : array
-    {
-        $collector = new FuncCallCollector();
-        $traverser = new Traverser($collector);
-        $traverser->traverse($this->parseResult);
-
-        $functions = [];
-
-        foreach ($collector->getFuncCalls() as $funcCall) {
-            $function = new FunctionCall($funcCall);
-
-            if ($function->name() === null) {
-                continue;
-            }
-
-            $functions[] = $function;
-        }
-
-        return $functions;
-    }
-
     public function raw() : ParseResult
     {
         return $this->parseResult;
     }
 
-    /**
-     * @return array<Table>
-     */
-    public function tables() : array
-    {
-        $collector = new RangeVarCollector();
-        $traverser = new Traverser($collector);
-        $traverser->traverse($this->parseResult);
-
-        $tables = [];
-
-        foreach ($collector->getRangeVars() as $rangeVar) {
-            $table = new Table($rangeVar);
-
-            if ($table->name() === '') {
-                continue;
-            }
-
-            $tables[] = $table;
-        }
-
-        return $tables;
-    }
-
     /**
      * Traverse the AST with visitors and/or modifiers.
      *