rawsql-ts 0.1.0-beta.4 → 0.1.0-beta.6

package/README.md

@@ -1,250 +1,164 @@
 # rawsql-ts
 
-A TypeScript SQL parser project that performs AST (Abstract Syntax Tree) analysis.
+rawsql-ts is a TypeScript SQL parser that performs Abstract Syntax Tree (AST) analysis for advanced SQL processing and transformation.
+
+> **Note:** This library is currently in beta. The API may change without notice until the v1.0 release.
 
 ## Installation
 
-Install the main project:
+Install the package from npm as follows:
 
 ```bash
-npm install
+npm install rawsql-ts
 ```
 
 ## Usage
 
-Build the project:
+Basic usage example:
 
-```bash
-npm run build
+```typescript
+import { SelectQueryParser } from 'rawsql-ts';
+import { Formatter } from 'rawsql-ts';
+
+const sql = `SELECT id, name FROM users WHERE active = TRUE`;
+const query = SelectQueryParser.parseFromText(sql);
+const formatter = new Formatter();
+const formattedSql = formatter.visit(query);
+console.log(formattedSql);
+// => select "id", "name" from "users" where "active" = true
 ```
 
-Run tests:
+---
 
-```bash
-npm test
-```
+## 🧩 Parsing Features
 
-## ✅ Supported Features
+rawsql-ts provides the following main parser class for converting SQL text into an Abstract Syntax Tree (AST):
 
-**Main features included in this parser:**
+- **SelectQueryParser**  
+  Parses complete SELECT and VALUES queries, including support for CTEs (WITH), UNION/INTERSECT/EXCEPT, subqueries, and all major SQL clauses. Handles PostgreSQL-specific syntax and advanced query structures.
 
-- **CTE Support**: Full Common Table Expression parsing
-  - PostgreSQL `MATERIALIZED`/`NOT MATERIALIZED` options
-  - Nested and recursive CTEs
-- **UNION Queries**: Handles UNION, UNION ALL, INTERSECT and EXCEPT
-- **Complex Subqueries**: Supports subqueries and inline queries
-- **Window Functions**: Complete WINDOW clause and function support
-- **PostgreSQL Optimized**: Deep support for PostgreSQL syntax
-  - `DISTINCT ON (columns)` expressions
-  - Array and range operators
+ **Key methods:**
+  - `parseFromText(sql: string): SelectQuery`  
+    Parses a SQL string and returns the root AST node for the query. Throws an error if the SQL is invalid or contains extra tokens.
+  - `parse(lexemes: Lexeme[], index: number): { value: SelectQuery; newIndex: number }`  
+    Parses a tokenized SQL query from the given index and returns the AST node and the new index. Used internally for advanced parsing scenarios.
 
-## ⚠️ Important Notes
+  **Notes:**
+  - Only PostgreSQL syntax is supported at this time.
+  - Only SELECT and VALUES queries are supported (INSERT/UPDATE/DELETE are not yet implemented).
+  - All SQL comments are removed during parsing.
 
-**Under development with the following limitations:**
+  This class is designed to handle all practical SQL parsing needs for SELECT/VALUES queries in PostgreSQL, including:
+  - CTEs (WITH), including recursive and materialized options
+  - UNION, INTERSECT, EXCEPT, and subqueries
+  - Window functions and analytic clauses
+  - Complex expressions, functions, and operators
+  - Robust error handling with detailed messages
+  - Accurate tokenization, including comments and special literals
 
-- **PostgreSQL Only**: Only PostgreSQL syntax is currently supported
-- **Comments Stripped**: SQL comments are removed during parsing
-- **SELECT Queries Only**: Currently only handles SELECT queries (no INSERT/UPDATE/DELETE)
-- **One-line Formatting**: Currently only supports single-line (compact) output formatting
-- **Beta Status**: API may change without notice until v1.0 release
+---
 
-## Transformer Utilities
+## Core SQL Query Classes
 
-rawsql-ts includes powerful transformer utilities to analyze and transform SQL ASTs. These utilities let you format, analyze, and extract information from SQL queries in a super flexible way!
+The following classes are the primary building blocks for representing and manipulating SQL queries in rawsql-ts:
 
-### Formatter
+### SimpleSelectQuery
 
-The Formatter transforms SQL ASTs into clean, standardized SQL text output. It handles all SQL components, ensuring proper escaping and consistent formatting regardless of the complexity of your queries.
+Represents a single, standard SQL SELECT statement (not a UNION or VALUES). This class encapsulates all major clauses such as SELECT, FROM, WHERE, GROUP BY, HAVING, ORDER BY, and more.
 
-```typescript
-import { SelectQueryParser } from './parsers/SelectQueryParser';
-import { Formatter } from './transformers/Formatter';
-
-// Example complex query with subquery and functions
-const sql = `
-SELECT
-    p.product_id
-    , p.name
-    , SUM(o.quantity) AS total_ordered
-    , CASE
-        WHEN SUM(o.quantity) > 1000 THEN 'High Demand'
-        WHEN SUM(o.quantity) > 500 THEN 'Medium Demand'
-        ELSE 'Low Demand'
-    END AS demand_category
-FROM
-    products AS p
-    JOIN order_items AS o ON p.product_id = o.product_id
-WHERE
-    p.category IN (
-        SELECT
-            category
-        FROM
-            featured_categories
-        WHERE
-            active = TRUE
-    )
-GROUP BY
-    p.product_id
-    , p.name
-HAVING
-    SUM(o.quantity) > 100
-ORDER BY
-    total_ordered DESC`;
-
-// Parse the query into an AST
-const query = SelectQueryParser.parseFromText(sql);
+**Key methods:**
+- `toUnion`, `toUnionAll`, `toIntersect`, `toExcept`, etc.
+  - Combine this query with another using UNION, INTERSECT, EXCEPT, etc., returning a BinarySelectQuery.
+- `appendWhere`, `appendWhereRaw`
+  - Add a new condition to the WHERE clause (as AST or raw SQL string).
+- `appendHaving`, `appendHavingRaw`
+  - Add a new condition to the HAVING clause.
+- `innerJoin`, `leftJoin`, `rightJoin`, `innerJoinRaw`, etc.
+  - Add JOIN clauses to the query, either as AST or from raw SQL.
+- `toSource`
+  - Wrap this query as a subquery (for use in FROM/JOIN, etc.).
+- `appendWith`, `appendWithRaw`
+  - Add CTEs (WITH clause) to the query.
 
-// Format the AST back to SQL
-const formatter = new Formatter();
-const formattedSql = formatter.visit(query);
+### BinarySelectQuery
 
-console.log(formattedSql);
-// Outputs clean, consistently formatted SQL with proper identifiers
-```
+Represents a binary SQL query, such as `SELECT ... UNION SELECT ...`, `INTERSECT`, or `EXCEPT`. This class holds a left and right query and the operator between them.
 
-### SelectValueCollector
+**Key methods:**
+- `union`, `unionAll`, `intersect`, `intersectAll`, `except`, `exceptAll`
+  - Chain additional queries to the current binary query.
+- `appendSelectQuery`
+  - Add a new query with a custom operator.
+- `toSource`
+  - Wrap this binary query as a subquery (for use in FROM/JOIN, etc.).
+- `unionRaw`, `intersectRaw`, etc.
+  - Add a new query by parsing a raw SQL string and combining it.
 
-The SelectValueCollector extracts all column items from a SELECT clause, including their aliases and expressions. It provides access to both column names and their corresponding value expressions, making it perfect for analyzing the output structure of SQL queries. For information on wildcard resolution (like `*` or `table.*`), see the Wildcard Resolution section below.
+### ValuesQuery
 
-```typescript
-import { SelectQueryParser } from './parsers/SelectQueryParser';
-import { SelectValueCollector } from './transformers/SelectValueCollector';
-import { Formatter } from './transformers/Formatter';
-
-// Example query with column references and expressions
-const sql = `
-SELECT
-    id
-    , name
-    , price * quantity AS total
-    , (
-        SELECT
-            COUNT(*)
-        FROM
-            orders AS o
-        WHERE
-            o.customer_id = c.id
-    ) AS order_count
-FROM
-    customers AS c
-WHERE
-    status = 'active'`;
+Represents a SQL `VALUES` clause, such as `VALUES (1, 'a'), (2, 'b')`, which is used for inline data tables.
 
-const query = SelectQueryParser.parseFromText(sql);
+**Key methods:**
+- (Primarily the constructor and tuple access)
+- This class can be used as a subquery source or wrapped with QueryNormalizer to convert it into a standard SELECT query.
 
-// Collect all select values
-const collector = new SelectValueCollector();
-const items = collector.collect(query);
+---
 
-// Format expressions for display
-const formatter = new Formatter();
+These classes are designed to be flexible and allow for robust construction, combination, and transformation of SQL queries. For further details, please refer to the source code.
 
-// Output column names
-console.log(items.map(item => item.name));
-// ["id", "name", "total", "order_count"]
+---
 
-// Output column expressions to show full value components
-console.log(items.map(item => formatter.visit(item.value)));
-// ["id", "name", "price * quantity", "(SELECT COUNT(*) FROM orders AS o WHERE o.customer_id = c.id)"]
-```
+## 🛠️ Transformer Features (AST Transformers)
 
-### SelectableColumnCollector
+rawsql-ts provides a suite of AST (Abstract Syntax Tree) transformers for advanced SQL analysis and manipulation. These utilities are intended for engineers who require programmatic extraction, analysis, or transformation of SQL query structures.
 
-The SelectableColumnCollector identifies all column references throughout a query that could potentially be included in a SELECT clause. It scans the entire query structure and extracts columns with their full context, making it ideal for query builders. For information on wildcard resolution (like `*` or `table.*`), see the Wildcard Resolution section below.
+### Main Transformers
 
-```typescript
-import { SelectQueryParser } from './parsers/SelectQueryParser';
-import { SelectableColumnCollector } from './transformers/SelectableColumnCollector';
-import { Formatter } from './transformers/Formatter';
-
-// Example query
-const sql = `
-SELECT
-    u.id
-    , u.name
-FROM
-    users AS u
-    JOIN profiles AS p ON u.id = p.user_id
-WHERE
-    u.active = TRUE
-    AND p.verified = TRUE`;
+- **Formatter**  
+  Converts SQL ASTs into standardized SQL text, handling identifier escaping and formatting for all SQL components.  
+  **Note:** Output formatting is currently limited to single-line (compact) style.
 
-const query = SelectQueryParser.parseFromText(sql);
-const collector = new SelectableColumnCollector();
+- **SelectValueCollector**  
+  Extracts all columns, including aliases and expressions, from SELECT clauses. Supports wildcard expansion (e.g., `*`, `table.*`) when table structure information is provided.
 
-// Collect all column references from data sources
-collector.visit(query);
-const columns = collector.collect(query);
+- **SelectableColumnCollector**  
+  Collects all column references in a query that can be included in a SELECT clause. Gathers all columns available from root FROM/JOIN sources.
 
-// Format column references for display
-const formatter = new Formatter();
-const columnNames = columns.map(item => item.name);
-console.log(columnNames);
-// ["id", "name", "active", "user_id", "verified"]
-
-// Get the original column expressions with their full context
-const expressions = columns.map(item => formatter.visit(item.value));
-console.log(expressions);
-// ["u.id", "u.name", "u.active", "p.user_id", "p.verified"]
-```
+- **CTECollector**  
+  Collects all Common Table Expressions (CTEs) from WITH clauses, subqueries, and UNION queries. Supports both nested and recursive CTEs.
 
-### Wildcard Resolution
+- **UpstreamSelectQueryFinder**  
+  Identifies upstream SELECT queries that provide specific columns by traversing CTEs, subqueries, and UNION branches.
 
-The wildcard resolution feature enhances both collectors by supporting the expansion of wildcard expressions (`*` and `table.*`). Since SQL AST analysis alone cannot determine actual column names from wildcards, this feature allows you to provide table structure information through a custom resolver.
+- **CTENormalizer**  
+  Consolidates all Common Table Expressions (CTEs) from any part of a query (including nested subqueries, JOINs, and UNIONs) into a single root-level WITH clause. If duplicate CTE names with different definitions are detected, an error is thrown to prevent ambiguity.
 
-To use this feature, simply provide a `TableColumnResolver` function when creating a collector. This resolver maps table names to their column definitions, allowing the collectors to fully expand wildcard expressions into individual columns with proper context.
+- **QueryNormalizer**  
+  Converts any SELECT query (including UNION, EXCEPT, or VALUES queries) into a standard SimpleSelectQuery format. For UNION or EXCEPT, the query is wrapped as a subquery with an alias (e.g., SELECT * FROM (...)). For VALUES, sequential column names (column1, column2, ...) are generated and the VALUES are wrapped in a subquery. This ensures a predictable query structure for downstream processing.
 
-```typescript
-import { SelectQueryParser } from './parsers/SelectQueryParser';
-import { SelectValueCollector } from './transformers/SelectValueCollector';
-import { Formatter } from './transformers/Formatter';
-
-// Define a function to resolve column names from table names
-const tableColumnResolver = (tableName: string): string[] => {
-  // In real applications, this would fetch from database metadata or schema information
-  const tableColumns: Record<string, string[]> = {
-    'users': ['id', 'name', 'email', 'created_at'],
-    'posts': ['id', 'title', 'content', 'user_id', 'created_at'],
-    'comments': ['id', 'post_id', 'user_id', 'content', 'created_at']
-  };
-  
-  return tableColumns[tableName] || [];
-};
-
-// Query containing wildcards
-const sql = `
-SELECT
-    u.*
-    , p.title
-    , p.content
-FROM
-    users AS u
-    JOIN posts AS p ON u.id = p.user_id
-WHERE
-    u.created_at > '2023-01-01'`;
+--- 
 
-const query = SelectQueryParser.parseFromText(sql);
+### Example Usage
 
-// Pass the TableColumnResolver to resolve wildcards
-const collector = new SelectValueCollector(tableColumnResolver);
-const items = collector.collect(query);
+```typescript
+import { SelectQueryParser } from 'rawsql-ts';
+import { SelectableColumnCollector } from 'rawsql-ts/transformers/SelectableColumnCollector';
 
-// Display results
-const formatter = new Formatter();
-console.log(items.map(item => item.name));
-// ["id", "name", "email", "created_at", "title", "content"]
+const sql = `SELECT u.id, u.name FROM users u JOIN posts p ON u.id = p.user_id`;
+const query = SelectQueryParser.parseFromText(sql);
 
-// Show full reference expressions for each column
-console.log(items.map(item => formatter.visit(item.value)));
-// ["u.id", "u.name", "u.email", "u.created_at", "p.title", "p.content"]
+const collector = new SelectableColumnCollector();
+const columns = collector.collect(query);
+console.log(columns.map(col => col.name)); // ["id", "name", "user_id", ...]
 ```
 
-This capability allows you to parse queries containing wildcards and understand exactly which columns are being referenced. It also supports expansion of wildcards from multiple tables and subqueries.
+---
+
+By utilizing these transformer utilities, you can perform advanced SQL analysis and manipulation with reliability and consistency.
 
 ## Benchmarks
 
-This project includes benchmarking functionality.
-To run benchmarks:
+This project includes benchmarking functionality. To run benchmarks, execute:
 
 ```bash
 npm run benchmark
@@ -252,12 +166,12 @@ npm run benchmark
 
 ## Benchmark Details
 
-This benchmark evaluates the SQL parsing and formatting performance of `rawsql-ts` against popular libraries: `sql-formatter` and `node-sql-parser`. We test queries of varying complexity:
+The benchmark suite evaluates the SQL parsing and formatting performance of `rawsql-ts` in comparison to popular libraries such as `sql-formatter` and `node-sql-parser`. Queries of varying complexity are tested:
 
 - **Tokens20**: Simple `SELECT` query with a basic `WHERE` condition (~20 tokens)
 - **Tokens70**: Medium complexity query with `JOIN`s and multiple conditions (~70 tokens)
 - **Tokens140**: Complex query with `CTE`s and aggregations (~140 tokens)
-- **Tokens230**: Very complex query with multiple `CTE`s, subqueries, and window functions (~230 tokens)
+- **Tokens230**: Highly complex query with multiple `CTE`s, subqueries, and window functions (~230 tokens)
 
 ## Benchmark Environment
 
@@ -300,9 +214,39 @@ Node.js v22.14.0
 
 ## Performance Summary
 
-- `rawsql-ts` **consistently outperforms** both `node-sql-parser` and `sql-formatter` in all tested cases.
-- **4x faster** than `node-sql-parser`.
-- **9-10x faster** than `sql-formatter`.
-- Maintains **full SQL parsing capabilities** while significantly improving performance.
+- `rawsql-ts` consistently outperforms both `node-sql-parser` and `sql-formatter` in all tested scenarios.
+- Approximately 4x faster than `node-sql-parser`.
+- Approximately 9-10x faster than `sql-formatter`.
+- Maintains comprehensive SQL parsing capabilities while delivering significant performance improvements.
+
+> **Note:** These benchmarks are based on a specific hardware and software environment. Actual performance may vary depending on system configuration and workload.
+
+## Practical Example: Table Join
+
+Let's see how easy it is to join two tables using rawsql-ts! You don't need to know the internal structure of SelectQuery or worry about alias names—just specify the join key(s) and the library will generate the ON clause for you automatically.
+
+```typescript
+import { SelectQueryParser } from 'rawsql-ts';
+import { Formatter } from 'rawsql-ts';
+
+// Parse two separate queries
+const userQuery = SelectQueryParser.parseFromText('SELECT user_id, user_name FROM users');
+const postQuery = SelectQueryParser.parseFromText('SELECT post_id, user_id, title FROM posts');
+
+// Join the two queries using innerJoin
+// Just pass the join key(s) as an array, and the ON clause will be generated automatically!
+const joinedQuery = userQuery.innerJoin(postQuery, ['user_id']);
+
+// Format the joined query back to SQL
+const formatter = new Formatter();
+const sql = formatter.visit(joinedQuery);
+console.log(sql);
+// Output:
+// select "user_id", "user_name", "post_id", "title" from "users" inner join (select "post_id", "user_id", "title" from "posts") on "users"."user_id" = "posts"."user_id"
+```
 
-> ⚠️ **Note:** These benchmarks are based on a specific hardware and software environment. Actual performance may vary depending on system configuration and workload.
+**Point:**
+- You do not need to understand the internal code of SelectQuery to perform joins.
+- You only need to specify the join key(s) (e.g., `['user_id']`). The ON clause is generated for you.
+- Alias names and subquery details are handled automatically by the library, so you never have to worry about them!
+- This makes it super easy to join queries, even if you don't know the full structure of the SQL or the internal AST.

package/dist/index.js

@@ -0,0 +1,32 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Entry point for rawsql-ts package
+__exportStar(require("./parsers/SelectQueryParser"), exports);
+__exportStar(require("./models/BinarySelectQuery"), exports);
+__exportStar(require("./models/SelectQuery"), exports);
+__exportStar(require("./models/ValueComponent"), exports);
+__exportStar(require("./models/ValuesQuery"), exports);
+__exportStar(require("./transformers/CTECollector"), exports);
+__exportStar(require("./transformers/CTENormalizer"), exports);
+__exportStar(require("./transformers/Formatter"), exports);
+__exportStar(require("./transformers/QueryNormalizer"), exports);
+__exportStar(require("./transformers/SelectValueCollector"), exports);
+__exportStar(require("./transformers/SelectableColumnCollector"), exports);
+__exportStar(require("./transformers/TableSourceCollector"), exports);
+__exportStar(require("./transformers/UpstreamSelectQueryFinder"), exports);
+// Add more exports here if you want to expose additional public API
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oCAAoC;AACpC,8DAA4C;AAE5C,6DAA2C;AAC3C,uDAAqC;AACrC,0DAAwC;AACxC,uDAAqC;AAErC,8DAA4C;AAC5C,+DAA6C;AAC7C,2DAAyC;AACzC,iEAA+C;AAC/C,sEAAoD;AACpD,2EAAyD;AACzD,sEAAoD;AACpD,2EAAyD;AACzD,oEAAoE"}

package/dist/models/BinarySelectQuery.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BinarySelectQuery = void 0;
+const Clause_1 = require("./Clause");
+const SqlComponent_1 = require("./SqlComponent");
+const ValueComponent_1 = require("./ValueComponent");
+const CTENormalizer_1 = require("../transformers/CTENormalizer");
+const SelectQueryParser_1 = require("../parsers/SelectQueryParser");
+/**
+ * Represents a binary SELECT query (e.g., UNION, INTERSECT, EXCEPT).
+ */
+class BinarySelectQuery extends SqlComponent_1.SqlComponent {
+    constructor(left, operator, right) {
+        super();
+        this.left = left;
+        this.operator = new ValueComponent_1.RawString(operator);
+        this.right = right;
+    }
+    /**
+     * Appends another query to this binary query using UNION as the operator.
+     * This creates a new BinarySelectQuery where the left side is this binary query
+     * and the right side is the provided query.
+     *
+     * @param query The query to append with UNION
+     * @returns A new BinarySelectQuery representing "(this) UNION query"
+     */
+    union(query) {
+        return this.appendSelectQuery('union', query);
+    }
+    /**
+     * Appends another query to this binary query using UNION ALL as the operator.
+     * This creates a new BinarySelectQuery where the left side is this binary query
+     * and the right side is the provided query.
+     *
+     * @param query The query to append with UNION ALL
+     * @returns A new BinarySelectQuery representing "(this) UNION ALL query"
+     */
+    unionAll(query) {
+        return this.appendSelectQuery('union all', query);
+    }
+    /**
+     * Appends another query to this binary query using INTERSECT as the operator.
+     * This creates a new BinarySelectQuery where the left side is this binary query
+     * and the right side is the provided query.
+     *
+     * @param query The query to append with INTERSECT
+     * @returns A new BinarySelectQuery representing "(this) INTERSECT query"
+     */
+    intersect(query) {
+        return this.appendSelectQuery('intersect', query);
+    }
+    /**
+     * Appends another query to this binary query using INTERSECT ALL as the operator.
+     * This creates a new BinarySelectQuery where the left side is this binary query
+     * and the right side is the provided query.
+     *
+     * @param query The query to append with INTERSECT ALL
+     * @returns A new BinarySelectQuery representing "(this) INTERSECT ALL query"
+     */
+    intersectAll(query) {
+        return this.appendSelectQuery('intersect all', query);
+    }
+    /**
+     * Appends another query to this binary query using EXCEPT as the operator.
+     * This creates a new BinarySelectQuery where the left side is this binary query
+     * and the right side is the provided query.
+     *
+     * @param query The query to append with EXCEPT
+     * @returns A new BinarySelectQuery representing "(this) EXCEPT query"
+     */
+    except(query) {
+        return this.appendSelectQuery('except', query);
+    }
+    /**
+     * Appends another query to this binary query using EXCEPT ALL as the operator.
+     * This creates a new BinarySelectQuery where the left side is this binary query
+     * and the right side is the provided query.
+     *
+     * @param query The query to append with EXCEPT ALL
+     * @returns A new BinarySelectQuery representing "(this) EXCEPT ALL query"
+     */
+    exceptAll(query) {
+        return this.appendSelectQuery('except all', query);
+    }
+    /**
+     * Appends another query to this binary query using the specified operator.
+     * This creates a new BinarySelectQuery where the left side is this binary query
+     * and the right side is the provided query.
+     *
+     * @param operator SQL operator to use (e.g. 'union', 'union all', 'intersect', 'except')
+     * @param query The query to append with the specified operator
+     * @returns A new BinarySelectQuery representing "(this) [operator] query"
+     */
+    appendSelectQuery(operator, query) {
+        this.left = new BinarySelectQuery(this.left, this.operator.value, this.right);
+        this.operator = new ValueComponent_1.RawString(operator);
+        this.right = query;
+        const normalizer = new CTENormalizer_1.CTENormalizer();
+        normalizer.normalize(this);
+        return this;
+    }
+    /**
+     * Appends another query to this binary query using UNION as the operator, accepting a raw SQL string.
+     * This method parses the SQL string and appends the resulting query using UNION.
+     * @param sql The SQL string to parse and union
+     * @returns A new BinarySelectQuery representing "(this) UNION (parsed query)"
+     */
+    unionRaw(sql) {
+        const parsedQuery = SelectQueryParser_1.SelectQueryParser.parseFromText(sql);
+        return this.union(parsedQuery);
+    }
+    unionAllRaw(sql) {
+        const parsedQuery = SelectQueryParser_1.SelectQueryParser.parseFromText(sql);
+        return this.unionAll(parsedQuery);
+    }
+    intersectRaw(sql) {
+        const parsedQuery = SelectQueryParser_1.SelectQueryParser.parseFromText(sql);
+        return this.intersect(parsedQuery);
+    }
+    intersectAllRaw(sql) {
+        const parsedQuery = SelectQueryParser_1.SelectQueryParser.parseFromText(sql);
+        return this.intersectAll(parsedQuery);
+    }
+    exceptRaw(sql) {
+        const parsedQuery = SelectQueryParser_1.SelectQueryParser.parseFromText(sql);
+        return this.except(parsedQuery);
+    }
+    exceptAllRaw(sql) {
+        const parsedQuery = SelectQueryParser_1.SelectQueryParser.parseFromText(sql);
+        return this.exceptAll(parsedQuery);
+    }
+    // Returns a SourceExpression wrapping this query as a subquery source.
+    // Optionally takes an alias name (default: "subq")
+    toSource(alias = "subq") {
+        return new Clause_1.SourceExpression(new Clause_1.SubQuerySource(this), new Clause_1.SourceAliasExpression(alias, null));
+    }
+}
+exports.BinarySelectQuery = BinarySelectQuery;
+BinarySelectQuery.kind = Symbol("BinarySelectQuery");
+//# sourceMappingURL=BinarySelectQuery.js.map

package/dist/models/BinarySelectQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BinarySelectQuery.js","sourceRoot":"","sources":["../../src/models/BinarySelectQuery.ts"],"names":[],"mappings":"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"}