rawsql-ts 0.11.19-beta → 0.11.21-beta

package/dist/esm/src/index.d.ts

@@ -1,5 +1,6 @@
 export * from './parsers/SelectQueryParser';
 export * from './parsers/InsertQueryParser';
+export * from './parsers/WithClauseParser';
 export * from './models/BinarySelectQuery';
 export * from './models/SelectQuery';
 export * from './models/ValueComponent';
@@ -20,6 +21,7 @@ export * from './transformers/PostgresJsonQueryBuilder';
 export * from './transformers/QueryBuilder';
 export * from './transformers/SelectValueCollector';
 export * from './transformers/SelectableColumnCollector';
+export { DuplicateDetectionMode } from './transformers/SelectableColumnCollector';
 export * from './transformers/TableColumnResolver';
 export * from './transformers/TableSourceCollector';
 export * from './transformers/JsonMappingConverter';

package/dist/esm/src/index.js

@@ -1,6 +1,7 @@
 // Entry point for rawsql-ts package
 export * from './parsers/SelectQueryParser';
 export * from './parsers/InsertQueryParser';
+export * from './parsers/WithClauseParser';
 export * from './models/BinarySelectQuery';
 export * from './models/SelectQuery';
 export * from './models/ValueComponent';
@@ -21,6 +22,7 @@ export * from './transformers/PostgresJsonQueryBuilder';
 export * from './transformers/QueryBuilder'; // old name:QueryConverter
 export * from './transformers/SelectValueCollector';
 export * from './transformers/SelectableColumnCollector';
+export { DuplicateDetectionMode } from './transformers/SelectableColumnCollector';
 export * from './transformers/TableColumnResolver';
 export * from './transformers/TableSourceCollector';
 export * from './transformers/JsonMappingConverter';

package/dist/esm/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAE5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAEhC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sCAAsC,CAAC;AACrD,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yCAAyC,CAAC;AACxD,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yCAAyC,CAAC;AACxD,cAAc,6BAA6B,CAAC,CAAC,0BAA0B;AACvE,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,oCAAoC,CAAC;AACnD,OAAO,EAEH,yBAAyB,EACzB,0BAA0B,EAK7B,MAAM,uCAAuC,CAAC;AAC/C,OAAO;AACH,6DAA6D;AAC7D,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,cAAc,EACjB,MAAM,mCAAmC,CAAC;AAE3C,qEAAqE;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,cAAc,0CAA0C,CAAC;AACzD,cAAc,gDAAgD,CAAC;AAE/D,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0CAA0C,CAAC;AACzD,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sCAAsC,CAAC;AACrD,cAAc,oCAAoC,CAAC;AAEnD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AAGrC,oEAAoE"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAE3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAEhC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sCAAsC,CAAC;AACrD,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yCAAyC,CAAC;AACxD,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yCAAyC,CAAC;AACxD,cAAc,6BAA6B,CAAC,CAAC,0BAA0B;AACvE,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAClF,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,oCAAoC,CAAC;AACnD,OAAO,EAEH,yBAAyB,EACzB,0BAA0B,EAK7B,MAAM,uCAAuC,CAAC;AAC/C,OAAO;AACH,6DAA6D;AAC7D,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,cAAc,EACjB,MAAM,mCAAmC,CAAC;AAE3C,qEAAqE;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,cAAc,0CAA0C,CAAC;AACzD,cAAc,gDAAgD,CAAC;AAE/D,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0CAA0C,CAAC;AACzD,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sCAAsC,CAAC;AACrD,cAAc,oCAAoC,CAAC;AAEnD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AAGrC,oEAAoE"}

package/dist/esm/src/parsers/WithClauseParser.d.ts

@@ -1,7 +1,58 @@
 import { WithClause } from "../models/Clause";
 import { Lexeme } from "../models/Lexeme";
+/**
+ * Parser for SQL WITH clauses (Common Table Expressions - CTEs).
+ * Parses only the WITH clause portion of SQL, not the entire query.
+ *
+ * **Note**: For most use cases, use `SelectQueryParser` which provides more comprehensive SQL parsing.
+ * This parser should only be used for the special case where you need to analyze only the WITH clause portion.
+ *
+ * @example
+ * ```typescript
+ * // Parses only the WITH clause, not the following SELECT
+ * const sql = "WITH recursive_cte AS (SELECT 1 as n UNION SELECT n+1 FROM recursive_cte WHERE n < 10)";
+ * const withClause = WithClauseParser.parse(sql);
+ * console.log(withClause.recursive); // true
+ * console.log(withClause.tables.length); // 1
+ * ```
+ */
 export declare class WithClauseParser {
+    /**
+     * Parses a SQL string containing only a WITH clause into a WithClause AST.
+     * The input should contain only the WITH clause, not the subsequent main query.
+     *
+     * @param query - The SQL string containing only the WITH clause
+     * @returns The parsed WithClause object
+     * @throws Error if the syntax is invalid or there are unexpected tokens after the WITH clause
+     *
+     * @example
+     * ```typescript
+     * // Correct: Only the WITH clause
+     * const sql = "WITH users_data AS (SELECT id, name FROM users)";
+     * const withClause = WithClauseParser.parse(sql);
+     *
+     * // Error: Contains SELECT after WITH clause
+     * // const badSql = "WITH users_data AS (SELECT id, name FROM users) SELECT * FROM users_data";
+     * ```
+     */
     static parse(query: string): WithClause;
+    /**
+     * Parses a WITH clause from an array of lexemes starting at the specified index.
+     *
+     * @param lexemes - Array of lexemes to parse from
+     * @param index - Starting index in the lexemes array
+     * @returns Object containing the parsed WithClause and the new index position
+     * @throws Error if the syntax is invalid or WITH keyword is not found
+     *
+     * @example
+     * ```typescript
+     * const tokenizer = new SqlTokenizer("WITH cte AS (SELECT 1)");
+     * const lexemes = tokenizer.readLexmes();
+     * const result = WithClauseParser.parseFromLexeme(lexemes, 0);
+     * console.log(result.value.tables.length); // 1
+     * console.log(result.newIndex); // position after the WITH clause
+     * ```
+     */
     static parseFromLexeme(lexemes: Lexeme[], index: number): {
         value: WithClause;
         newIndex: number;

package/dist/esm/src/parsers/WithClauseParser.js

@@ -2,8 +2,41 @@ import { WithClause } from "../models/Clause";
 import { TokenType } from "../models/Lexeme";
 import { SqlTokenizer } from "./SqlTokenizer";
 import { CommonTableParser } from "./CommonTableParser";
+/**
+ * Parser for SQL WITH clauses (Common Table Expressions - CTEs).
+ * Parses only the WITH clause portion of SQL, not the entire query.
+ *
+ * **Note**: For most use cases, use `SelectQueryParser` which provides more comprehensive SQL parsing.
+ * This parser should only be used for the special case where you need to analyze only the WITH clause portion.
+ *
+ * @example
+ * ```typescript
+ * // Parses only the WITH clause, not the following SELECT
+ * const sql = "WITH recursive_cte AS (SELECT 1 as n UNION SELECT n+1 FROM recursive_cte WHERE n < 10)";
+ * const withClause = WithClauseParser.parse(sql);
+ * console.log(withClause.recursive); // true
+ * console.log(withClause.tables.length); // 1
+ * ```
+ */
 export class WithClauseParser {
-    // Parse SQL string to AST (was: parse)
+    /**
+     * Parses a SQL string containing only a WITH clause into a WithClause AST.
+     * The input should contain only the WITH clause, not the subsequent main query.
+     *
+     * @param query - The SQL string containing only the WITH clause
+     * @returns The parsed WithClause object
+     * @throws Error if the syntax is invalid or there are unexpected tokens after the WITH clause
+     *
+     * @example
+     * ```typescript
+     * // Correct: Only the WITH clause
+     * const sql = "WITH users_data AS (SELECT id, name FROM users)";
+     * const withClause = WithClauseParser.parse(sql);
+     *
+     * // Error: Contains SELECT after WITH clause
+     * // const badSql = "WITH users_data AS (SELECT id, name FROM users) SELECT * FROM users_data";
+     * ```
+     */
     static parse(query) {
         const tokenizer = new SqlTokenizer(query); // Initialize tokenizer
         const lexemes = tokenizer.readLexmes(); // Get tokens
@@ -15,7 +48,23 @@ export class WithClauseParser {
         }
         return result.value;
     }
-    // Parse from lexeme array (was: parse)
+    /**
+     * Parses a WITH clause from an array of lexemes starting at the specified index.
+     *
+     * @param lexemes - Array of lexemes to parse from
+     * @param index - Starting index in the lexemes array
+     * @returns Object containing the parsed WithClause and the new index position
+     * @throws Error if the syntax is invalid or WITH keyword is not found
+     *
+     * @example
+     * ```typescript
+     * const tokenizer = new SqlTokenizer("WITH cte AS (SELECT 1)");
+     * const lexemes = tokenizer.readLexmes();
+     * const result = WithClauseParser.parseFromLexeme(lexemes, 0);
+     * console.log(result.value.tables.length); // 1
+     * console.log(result.newIndex); // position after the WITH clause
+     * ```
+     */
     static parseFromLexeme(lexemes, index) {
         let idx = index;
         // Capture comments from the WITH keyword

package/dist/esm/src/parsers/WithClauseParser.js.map

@@ -1 +1 @@
-{"version":3,"file":"WithClauseParser.js","sourceRoot":"","sources":["../../../../src/parsers/WithClauseParser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAU,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,OAAO,gBAAgB;IACzB,uCAAuC;IAChC,MAAM,CAAC,KAAK,CAAC,KAAa;QAC7B,MAAM,SAAS,GAAG,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,uBAAuB;QAClE,MAAM,OAAO,GAAG,SAAS,CAAC,UAAU,EAAE,CAAC,CAAC,aAAa;QAErD,QAAQ;QACR,MAAM,MAAM,GAAG,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAEhD,sCAAsC;QACtC,IAAI,MAAM,CAAC,QAAQ,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,mCAAmC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,iBAAiB,MAAM,CAAC,QAAQ,gEAAgE,CAAC,CAAC;QACvL,CAAC;QAED,OAAO,MAAM,CAAC,KAAK,CAAC;IACxB,CAAC;IAED,uCAAuC;IAChC,MAAM,CAAC,eAAe,CAAC,OAAiB,EAAE,KAAa;QAC1D,IAAI,GAAG,GAAG,KAAK,CAAC;QAEhB,yCAAyC;QACzC,MAAM,iBAAiB,GAAG,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;QAE9E,sBAAsB;QACtB,IAAI,GAAG,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;YACtE,GAAG,EAAE,CAAC;QACV,CAAC;aAAM,CAAC;YACJ,MAAM,IAAI,KAAK,CAAC,4BAA4B,GAAG,0BAA0B,CAAC,CAAC;QAC/E,CAAC;QAED,8BAA8B;QAC9B,MAAM,SAAS,GAAG,GAAG,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,WAAW,CAAC;QAC3F,IAAI,SAAS,EAAE,CAAC;YACZ,GAAG,EAAE,CAAC;QACV,CAAC;QAED,aAAa;QACb,MAAM,MAAM,GAAkB,EAAE,CAAC;QAEjC,6BAA6B;QAC7B,MAAM,QAAQ,GAAG,iBAAiB,CAAC,eAAe,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACjE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC5B,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC;QAExB,mCAAmC;QACnC,OAAO,GAAG,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACnE,GAAG,EAAE,CAAC,CAAC,aAAa;YAEpB,wDAAwD;YACxD,yEAAyE;YACzE,MAAM,SAAS,GAAG,iBAAiB,CAAC,eAAe,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YAClE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YAC7B,GAAG,GAAG,SAAS,CAAC,QAAQ,CAAC;QAC7B,CAAC;QAED,mCAAmC;QACnC,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QACrD,UAAU,CAAC,QAAQ,GAAG,iBAAiB,CAAC;QAExC,OAAO;YACH,KAAK,EAAE,UAAU;YACjB,QAAQ,EAAE,GAAG;SAChB,CAAC;IACN,CAAC;CACJ"}
+{"version":3,"file":"WithClauseParser.js","sourceRoot":"","sources":["../../../../src/parsers/WithClauseParser.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/transformers/SelectableColumnCollector.d.ts

@@ -20,28 +20,58 @@ import { SqlComponent, SqlComponentVisitor } from "../models/SqlComponent";
 import { ValueComponent } from "../models/ValueComponent";
 import { TableColumnResolver } from "./TableColumnResolver";
 /**
- * A visitor that collects all ColumnReference instances from SimpleSelectQuery structures.
+ * A visitor that collects all ColumnReference instances from SQL query structures.
  * This visitor scans through all clauses and collects all unique ColumnReference objects.
- * It does not scan Common Table Expressions (CTEs) or subqueries.
+ * It supports both regular column collection and upstream column collection for maximum
+ * search conditions in DynamicQuery scenarios.
  *
- * IMPORTANT: This collector only supports SimpleSelectQuery. BinarySelectQuery
- * (UNION/INTERSECT/EXCEPT) will throw an error and should be decomposed into
- * individual SimpleSelectQuery branches before using this collector.
+ * Supported query types:
+ * - SimpleSelectQuery: Basic SELECT queries with all standard clauses
+ * - BinarySelectQuery: UNION, INTERSECT, EXCEPT queries (collects from both sides)
+ * - Common Table Expressions (CTEs) within queries
+ * - Subqueries and nested queries
  *
  * Behavioral notes:
- * - Only collects column references to tables defined in the root FROM/JOIN clauses
+ * - Collects column references to tables defined in the root FROM/JOIN clauses
  * - For aliased columns (e.g., 'title as name'), collects both the original column
  *   reference ('title') AND the alias ('name') to enable complete dependency tracking
+ * - When upstream option is enabled, collects all available columns from upstream sources
+ *   (CTEs, subqueries, and tables) for maximum search conditions in DynamicQuery
+ * - Automatically removes duplicates based on the specified duplicate detection mode
  *
  * Use cases:
  * - Dependency analysis and schema migration tools
- * - Column usage tracking within individual SELECT branches
+ * - Column usage tracking across complex queries including unions and CTEs
  * - Security analysis for column-level access control
+ * - DynamicQuery maximum search condition column discovery
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - collect only referenced columns
+ * const collector = new SelectableColumnCollector();
+ * const columns = collector.collect(query);
+ *
+ * // With upstream collection for DynamicQuery
+ * const upstreamCollector = new SelectableColumnCollector(
+ *   null, false, DuplicateDetectionMode.ColumnNameOnly,
+ *   { upstream: true }
+ * );
+ * const allColumns = upstreamCollector.collect(query);
+ *
+ * // Works with union queries and CTEs
+ * const unionQuery = SelectQueryParser.parse(`
+ *   SELECT name, email FROM users
+ *   UNION
+ *   SELECT name, email FROM customers
+ * `);
+ * const unionColumns = collector.collect(unionQuery);
+ * ```
  */
 export declare class SelectableColumnCollector implements SqlComponentVisitor<void> {
     private handlers;
     private selectValues;
     private visitedNodes;
+    private uniqueKeys;
     private isRootVisit;
     private tableColumnResolver;
     private commonTableCollector;
@@ -57,10 +87,28 @@ export declare class SelectableColumnCollector implements SqlComponentVisitor<vo
      * @param {DuplicateDetectionMode} [duplicateDetection=DuplicateDetectionMode.ColumnNameOnly] - Specifies the duplicate detection mode: 'columnNameOnly' (default, only column name is used), or 'fullName' (table name + column name).
      * @param {Object} [options={}] - Additional options for the collector.
      * @param {boolean} [options.ignoreCaseAndUnderscore=false] - If true, column names are compared without considering case and underscores.
+     * @param {boolean} [options.upstream=false] - If true, collect all columns available from upstream sources for maximum search conditions in DynamicQuery.
      */
     constructor(tableColumnResolver?: TableColumnResolver | null, includeWildCard?: boolean, duplicateDetection?: DuplicateDetectionMode, options?: {
         ignoreCaseAndUnderscore?: boolean;
+        upstream?: boolean;
     });
+    /**
+     * Initialize instance properties.
+     */
+    private initializeProperties;
+    /**
+     * Initialize the handler map for different SQL component types.
+     */
+    private initializeHandlers;
+    /**
+     * Initialize handlers for SQL clause types.
+     */
+    private initializeClauseHandlers;
+    /**
+     * Initialize handlers for value component types.
+     */
+    private initializeValueComponentHandlers;
     getValues(): {
         name: string;
         value: ValueComponent;
@@ -75,10 +123,18 @@ export declare class SelectableColumnCollector implements SqlComponentVisitor<vo
     private reset;
     /**
      * Add a select value as unique, according to the duplicate detection option.
-     * If duplicateDetection is 'columnNameOnly', only column name is checked.
-     * If duplicateDetection is 'fullName', both table and column name are checked.
+     * Uses efficient Set-based duplicate detection for better performance.
      */
     private addSelectValueAsUnique;
+    /**
+     * Generate a unique key based on the duplicate detection mode.
+     */
+    private generateUniqueKey;
+    /**
+     * Normalize column name based on options.
+     * Ensures safe string handling to prevent injection attacks.
+     */
+    private normalizeColumnName;
     /**
      * Main entry point for the visitor pattern.
      * Implements the shallow visit pattern to distinguish between root and recursive visits.
@@ -93,6 +149,10 @@ export declare class SelectableColumnCollector implements SqlComponentVisitor<vo
       * Process a SimpleSelectQuery to collect ColumnReferences from all its clauses
       */
     private visitSimpleSelectQuery;
+    /**
+     * Process a BinarySelectQuery (UNION, INTERSECT, EXCEPT) to collect ColumnReferences from both sides
+     */
+    private visitBinarySelectQuery;
     private visitSelectClause;
     private visitFromClause;
     private visitWhereClause;
@@ -118,4 +178,29 @@ export declare class SelectableColumnCollector implements SqlComponentVisitor<vo
     private visitArrayQueryExpression;
     private visitValueList;
     private visitPartitionByClause;
+    /**
+     * Collect all upstream columns available for DynamicQuery maximum search conditions.
+     * This includes columns from CTEs, subqueries, and tables that can be used for filtering.
+     */
+    private collectUpstreamColumns;
+    /**
+     * Collect upstream columns from a specific source (table, subquery, or CTE).
+     */
+    private collectUpstreamColumnsFromSource;
+    /**
+     * Collect upstream columns from a table source using table column resolver.
+     */
+    private collectUpstreamColumnsFromTable;
+    /**
+     * Collect upstream columns from a subquery source.
+     */
+    private collectUpstreamColumnsFromSubquery;
+    /**
+     * Collect upstream columns from a CTE.
+     */
+    private collectUpstreamColumnsFromCTE;
+    /**
+     * Find a CTE by name in the common tables.
+     */
+    private findCTEByName;
 }