rawsql-ts 0.1.0-beta.1 → 0.1.0-beta.11

package/README.md

@@ -1,265 +1,202 @@
 # rawsql-ts
 
-A TypeScript SQL parser project that performs AST (Abstract Syntax Tree) analysis.
+![No external dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)
 
-## Installation
-
-Install the main project:
-
-```bash
-npm install
-```
+rawsql-ts is a high-performance SQL parser and AST transformer library written in TypeScript. It is designed for extensibility and advanced SQL analysis, with initial focus on PostgreSQL syntax but not limited to it. The library enables easy SQL parsing, transformation, and analysis for a wide range of SQL dialects.
 
-## Usage
+> **Note:** This library is currently in beta. The API may change until the v1.0 release.
 
-Build the project:
+---
 
-```bash
-npm run build
-```
-
-Run tests:
-
-```bash
-npm test
-```
+💡 **Key Advantages**
 
-## ✅ Supported Features
+With rawsql-ts, raw SQL can be represented as objects, enabling flexible manipulation of SQL statements directly within your program. Objectified SQL can be partially transformed, decomposed into manageable components, and recombined as needed. This approach dramatically improves the maintainability and reusability of complex SQL, making even large-scale queries easy to manage and refactor.
 
-**Main features included in this parser:**
+---
 
-- **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
+## Features
 
-## ⚠️ Important Notes
+- Zero dependencies: fully self-contained and lightweight
+- High-speed SQL parsing and AST analysis
+- Rich utilities for SQL structure transformation and analysis
 
-**Under development with the following limitations:**
-
-- **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
-
-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!
+## Installation
 
-### Formatter
+```bash
+npm install rawsql-ts
+```
 
-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.
+## Quick Start
 
 ```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);
-
-// Format the AST back to SQL
+import { SelectQueryParser, Formatter } from 'rawsql-ts';
+
+const sql = `SELECT user_id, name FROM users WHERE active = TRUE`;
+const query = SelectQueryParser.parse(sql);
 const formatter = new Formatter();
-const formattedSql = formatter.visit(query);
+const formattedSql = formatter.format(query);
 
 console.log(formattedSql);
-// Outputs clean, consistently formatted SQL with proper identifiers
+// => select "user_id", "name" from "users" where "active" = true
 ```
 
-### SelectValueCollector
-
-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.
+---
+
+## Main Parser Features
+
+- **SelectQueryParser**  
+  The main class for converting SELECT and VALUES statements into AST. Fully supports CTEs (WITH), UNION/INTERSECT/EXCEPT, subqueries, and PostgreSQL-specific syntax.
+  - `parse(sql: string): SelectQuery`  
+    Converts a SQL string to an AST. Throws an exception on error.
+  - Supports only PostgreSQL syntax
+  - Only SELECT and VALUES are supported (INSERT/UPDATE/DELETE are not yet implemented)
+  - SQL comments are automatically removed
+  - Handles CTEs (WITH), UNION/INTERSECT/EXCEPT, subqueries, window functions, complex expressions, and functions
+  - Provides detailed error messages
+  - Highly accurate tokenization
+
+---
+
+## Core SQL Query Classes
+
+- **SimpleSelectQuery**  
+  Represents a standard SELECT statement. Supports all major clauses such as WHERE, GROUP BY, JOIN, and CTE.
+  - `toUnion`, `toUnionAll`, ... for UNION operations
+  - `appendWhere`, `appendWhereRaw` to add WHERE conditions
+  - `innerJoin`, `leftJoin`, ... to add JOINs
+  - `toSource` to wrap as a subquery
+  - `appendWith`, `appendWithRaw` to add CTEs
+
+- **BinarySelectQuery**  
+  Represents binary SQL queries such as UNION, INTERSECT, and EXCEPT.
+  - `union`, `intersect`, ... to combine queries
+  - `toSource` to wrap as a subquery
+  - `unionRaw`, ... to combine with raw SQL
+
+- **ValuesQuery**  
+  For inline tables like `VALUES (1, 'a'), (2, 'b')`.
+  - Can be used as a subquery or converted to SELECT with QueryNormalizer
+
+---
+
+## AST Transformer Features
+
+A suite of utilities for transforming and analyzing SQL ASTs.
+
+### Main Transformers
+
+- **Formatter**  
+  Converts ASTs to formatted SQL strings. Handles identifier escaping. Output is currently single-line (compact) style.
+- **SelectValueCollector**  
+  Extracts all columns, aliases, and expressions from SELECT clauses. Supports wildcard expansion (e.g., `*`, `table.*`) with TableColumnResolver.
+- **SelectableColumnCollector**  
+  Collects all columns available from root FROM/JOIN sources.
+- **TableSourceCollector**  
+  Collects all table and subquery sources from FROM and JOIN clauses.
+- **CTECollector**  
+  Collects all CTEs from WITH clauses, subqueries, and UNION queries.
+- **UpstreamSelectQueryFinder**  
+  Finds upstream SELECT queries that provide specific columns by traversing CTEs, subqueries, and UNION branches.
+- **CTENormalizer**  
+  Consolidates all CTEs into a single root-level WITH clause. Throws an error if duplicate CTE names with different definitions are found.
+- **QueryNormalizer**  
+  Converts any SELECT/UNION/VALUES query into a standard SimpleSelectQuery. Handles subquery wrapping and automatic column name generation.
+- **TableColumnResolver**  
+  A function type for resolving column names from a table name, mainly used for wildcard expansion (e.g., `table.*`). Used by analyzers like SelectValueCollector.
+  ```typescript
+  export type TableColumnResolver = (tableName: string) => string[];
+  ```
+
+---
+
+## Usage Example
 
 ```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'`;
-
-const query = SelectQueryParser.parseFromText(sql);
-
-// Collect all select values
-const collector = new SelectValueCollector();
-const items = collector.collect(query);
-
-// Format expressions for display
-const formatter = new Formatter();
-
-// Output column names
-console.log(items.map(item => item.name));
-// ["id", "name", "total", "order_count"]
+import { TableColumnResolver } from "./src/transformers/TableColumnResolver";
+import { SelectQueryParser } from 'rawsql-ts';
+import { SelectableColumnCollector } from 'rawsql-ts/transformers/SelectableColumnCollector';
+import { SelectValueCollector } from 'rawsql-ts/transformers/SelectValueCollector';
+import { TableSourceCollector } from 'rawsql-ts/transformers/TableSourceCollector';
+
+// TableColumnResolver example
+const resolver: TableColumnResolver = (tableName) => {
+  if (tableName === "users") return ["id", "name", "email"];
+  if (tableName === "posts") return ["id", "title", "content"];
+  return [];
+};
 
-// 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)"]
-```
+const sql = `SELECT u.* FROM users u JOIN posts p ON u.id = p.user_id`;
+const query = SelectQueryParser.parse(sql);
 
-### SelectableColumnCollector
+// Wildcard expansion example
+const selectValueCollector = new SelectValueCollector(resolver);
+const selectValues = selectValueCollector.collect(query);
+console.log(selectValues.map(val => val.alias || val.expression.toString()));
 
-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.
+// Collect all selectable columns from FROM/JOIN sources
+const selectableColumnCollector = new SelectableColumnCollector();
+const selectableColumns = selectableColumnCollector.collect(query);
+console.log(selectableColumns.map(col => col.name));
 
-```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`;
-
-const query = SelectQueryParser.parseFromText(sql);
-const collector = new SelectableColumnCollector();
-
-// Collect all column references from data sources
-collector.visit(query);
-const columns = collector.collect(query);
-
-// 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"]
+// Collect all table and subquery sources from FROM/JOIN clauses
+const tableSourceCollector = new TableSourceCollector();
+const sources = tableSourceCollector.collect(query);
+console.log(sources.map(src => src.alias || src.name));
 ```
 
-### Wildcard Resolution
+---
 
-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.
+## Advanced Example: Table Join
 
-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.
+This example demonstrates how to join two tables using rawsql-ts. You do not need to understand the internal structure or manage aliases manually. By specifying the join key(s), the ON clause is generated automatically.
 
 ```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] || [];
-};
+import { SelectQueryParser, Formatter, SimpleSelectQuery } from 'rawsql-ts';
+
+// Parse the base query
+const query = SelectQueryParser.parse('SELECT u.user_id, u.name FROM users u') as SimpleSelectQuery;
+
+// Add LEFT JOIN using the leftJoinRaw method (join on user_id)
+query.leftJoinRaw('orders', 'o', ['user_id']);
+
+// Add WHERE clause
+query.appendWhereRaw('o.order_id IS NULL');
 
-// 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);
-
-// Pass the TableColumnResolver to resolve wildcards
-const collector = new SelectValueCollector(tableColumnResolver);
-const items = collector.collect(query);
-
-// Display results
 const formatter = new Formatter();
-console.log(items.map(item => item.name));
-// ["id", "name", "email", "created_at", "title", "content"]
+const formattedSql = formatter.format(query);
 
-// 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"]
+console.log(formattedSql);
+// => select "u"."user_id", "u"."name" from "users" as "u" left join "orders" as "o" on "u"."user_id" = "o"."user_id" where "o"."order_id" is null
 ```
 
-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.
+**Key Points:**
+- No need to understand internal implementation or alias management
+- Specify only the join key(s) (e.g., `['user_id']`); the ON clause is generated automatically
+- Subqueries and aliases are handled automatically
+- You can join queries without detailed knowledge of SQL structure or AST internals
+
+---
 
 ## Benchmarks
 
-This project includes benchmarking functionality.
-To run benchmarks:
+This project includes a comprehensive benchmark suite to evaluate the performance of `rawsql-ts` in comparison with other popular libraries such as `node-sql-parser` and `sql-formatter`.
+
+### How to Run
 
 ```bash
 npm run benchmark
 ```
 
-## Benchmark Details
+### 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 measures SQL parsing and formatting speed across queries of varying complexity:
 
-- **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)
+- **Tokens20**: Simple SELECT with a basic WHERE clause (~20 tokens)
+- **Tokens70**: Medium complexity query with JOINs and multiple conditions (~70 tokens)
+- **Tokens140**: Complex query with CTEs and aggregations (~140 tokens)
+- **Tokens230**: Highly complex query with multiple CTEs, subqueries, and window functions (~230 tokens)
 
-## Benchmark Environment
+### Benchmark Environment
 
 ```
 benchmark.js v2.1.4  
@@ -268,41 +205,46 @@ AMD Ryzen 7 7800X3D (8C/16T)
 Node.js v22.14.0
 ```
 
-## Results
-
-### Tokens20
-| Method                            | Mean       | Error     | StdDev    |
-|---------------------------------- |-----------:|----------:|----------:|
-| rawsql-ts                  |    0.021 ms |  0.0044 ms |  0.0023 ms |
-| node-sql-parser                |    0.169 ms |  0.0695 ms |  0.0355 ms |
-| sql-formatter                  |    0.208 ms |  0.0556 ms |  0.0284 ms |
-
-### Tokens70
-| Method                            | Mean       | Error     | StdDev    |
-|---------------------------------- |-----------:|----------:|----------:|
-| rawsql-ts                  |    0.057 ms |  0.0143 ms |  0.0073 ms |
-| node-sql-parser                |    0.216 ms |  0.0780 ms |  0.0398 ms |
-| sql-formatter                  |    0.512 ms |  0.1251 ms |  0.0638 ms |
-
-### Tokens140
-| Method                            | Mean       | Error     | StdDev    |
-|---------------------------------- |-----------:|----------:|----------:|
-| rawsql-ts                  |    0.112 ms |  0.0236 ms |  0.0120 ms |
-| node-sql-parser                |    0.404 ms |  0.0926 ms |  0.0472 ms |
-| sql-formatter                  |    1.004 ms |  0.3027 ms |  0.1545 ms |
-
-### Tokens230
-| Method                            | Mean       | Error     | StdDev    |
-|---------------------------------- |-----------:|----------:|----------:|
-| rawsql-ts                  |    0.182 ms |  0.0371 ms |  0.0189 ms |
-| node-sql-parser                |    0.865 ms |  0.3325 ms |  0.1696 ms |
-| sql-formatter                  |    1.696 ms |  0.2754 ms |  0.1405 ms |
-
-## 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.
-
-> ⚠️ **Note:** These benchmarks are based on a specific hardware and software environment. Actual performance may vary depending on system configuration and workload.
+### Results
+
+#### Tokens20
+| Method           | Mean      | Error     | StdDev    |
+|------------------|----------:|----------:|----------:|
+| rawsql-ts        | 0.021 ms  | 0.0044 ms | 0.0023 ms |
+| node-sql-parser  | 0.169 ms  | 0.0695 ms | 0.0355 ms |
+| sql-formatter    | 0.208 ms  | 0.0556 ms | 0.0284 ms |
+
+#### Tokens70
+| Method           | Mean      | Error     | StdDev    |
+|------------------|----------:|----------:|----------:|
+| rawsql-ts        | 0.057 ms  | 0.0143 ms | 0.0073 ms |
+| node-sql-parser  | 0.216 ms  | 0.0780 ms | 0.0398 ms |
+| sql-formatter    | 0.512 ms  | 0.1251 ms | 0.0638 ms |
+
+#### Tokens140
+| Method           | Mean      | Error     | StdDev    |
+|------------------|----------:|----------:|----------:|
+| rawsql-ts        | 0.112 ms  | 0.0236 ms | 0.0120 ms |
+| node-sql-parser  | 0.404 ms  | 0.0926 ms | 0.0472 ms |
+| sql-formatter    | 1.004 ms  | 0.3027 ms | 0.1545 ms |
+
+#### Tokens230
+| Method           | Mean      | Error     | StdDev    |
+|------------------|----------:|----------:|----------:|
+| rawsql-ts        | 0.182 ms  | 0.0371 ms | 0.0189 ms |
+| node-sql-parser  | 0.865 ms  | 0.3325 ms | 0.1696 ms |
+| sql-formatter    | 1.696 ms  | 0.2754 ms | 0.1405 ms |
+
+### Performance Summary
+
+- `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 high performance even with complex SQL while providing comprehensive features.
+
+> **Note:** These benchmarks are based on a specific hardware and software environment. Actual performance may vary depending on system configuration and query complexity.
+
+---
+
+Feel free to try rawsql-ts! Questions, requests, and bug reports are always welcome.
+

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export * from './parsers/SelectQueryParser';
+export * from './models/BinarySelectQuery';
+export * from './models/SelectQuery';
+export * from './models/ValueComponent';
+export * from './models/ValuesQuery';
+export * from './transformers/CTECollector';
+export * from './transformers/CTENormalizer';
+export * from './transformers/Formatter';
+export * from './transformers/QueryConverter';
+export * from './transformers/SelectValueCollector';
+export * from './transformers/SelectableColumnCollector';
+export * from './transformers/TableColumnResolver';
+export * from './transformers/TableSourceCollector';
+export * from './transformers/UpstreamSelectQueryFinder';

package/dist/index.js

@@ -0,0 +1,33 @@
+"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/QueryConverter"), exports);
+__exportStar(require("./transformers/SelectValueCollector"), exports);
+__exportStar(require("./transformers/SelectableColumnCollector"), exports);
+__exportStar(require("./transformers/TableColumnResolver"), 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,gEAA8C;AAC9C,sEAAoD;AACpD,2EAAyD;AACzD,qEAAmD;AACnD,sEAAoD;AACpD,2EAAyD;AACzD,oEAAoE"}

package/dist/models/BinarySelectQuery.d.ts

@@ -0,0 +1,91 @@
+import { SourceExpression } from "./Clause";
+import type { SelectQuery } from "./SelectQuery";
+import { SqlComponent } from "./SqlComponent";
+import { RawString } from "./ValueComponent";
+/**
+ * Represents a binary SELECT query (e.g., UNION, INTERSECT, EXCEPT).
+ */
+export declare class BinarySelectQuery extends SqlComponent {
+    static kind: symbol;
+    left: SelectQuery;
+    operator: RawString;
+    right: SelectQuery;
+    constructor(left: SelectQuery, operator: string, right: SelectQuery);
+    /**
+     * 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: SelectQuery): BinarySelectQuery;
+    /**
+     * 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: SelectQuery): BinarySelectQuery;
+    /**
+     * 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: SelectQuery): BinarySelectQuery;
+    /**
+     * 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: SelectQuery): BinarySelectQuery;
+    /**
+     * 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: SelectQuery): BinarySelectQuery;
+    /**
+     * 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: SelectQuery): BinarySelectQuery;
+    /**
+     * 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: string, query: SelectQuery): BinarySelectQuery;
+    /**
+     * 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: string): BinarySelectQuery;
+    unionAllRaw(sql: string): BinarySelectQuery;
+    intersectRaw(sql: string): BinarySelectQuery;
+    intersectAllRaw(sql: string): BinarySelectQuery;
+    exceptRaw(sql: string): BinarySelectQuery;
+    exceptAllRaw(sql: string): BinarySelectQuery;
+    toSource(alias?: string): SourceExpression;
+}