rawsql-ts 0.8.3-beta → 0.10.0-beta

package/README.md

@@ -8,32 +8,30 @@
 
 🌐 [Online Demo (GitHub Pages)](https://mk3008.github.io/rawsql-ts/)
 
-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.
+rawsql-ts is a high-performance SQL parser and AST transformer library written in TypeScript. It empowers you to represent raw SQL as objects, enabling flexible manipulation of SQL statements directly within your program. This object-oriented approach allows for partial transformation, decomposition into manageable components, and recombination as needed, dramatically improving the maintainability and reusability of complex SQL.
+
+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.
 
 > [!Note]
 > This library is currently in beta. The API may change until the v1.0 release.
 
 ---
 
-💡 **Key Advantages**
-
-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.
-
----
-
-## Features
+## Key Features
 
 - Zero dependencies: fully self-contained and lightweight
 - High-speed SQL parsing and AST analysis (over 3x faster than major libraries)
 - Rich utilities for SQL structure transformation and analysis
 - Advanced SQL formatting capabilities, including multi-line formatting and customizable styles
+- Dynamic SQL parameter injection for building flexible search queries with `SqlParamInjector`
+- Static query validation and regression testing against your database schema with `SqlSchemaValidator`, enabling early error detection and robust unit tests for schema changes.
 
-![Benchmark Results](https://quickchart.io/chart?c={type:'bar',data:{labels:['Tokens20','Tokens70','Tokens140','Tokens230'],datasets:[{label:'rawsql-ts',data:[0.029,0.075,0.137,0.239],backgroundColor:'rgba(54,162,235,0.8)',borderColor:'rgba(54,162,235,1)',borderWidth:1},{label:'node-sql-parser',data:[0.210,0.223,0.420,0.871],backgroundColor:'rgba(255,206,86,0.8)',borderColor:'rgba(255,206,86,1)',borderWidth:1},{label:'sql-formatter',data:[0.228,0.547,1.057,1.906],backgroundColor:'rgba(255,99,132,0.8)',borderColor:'rgba(255,99,132,1)',borderWidth:1}]},options:{plugins:{legend:{labels:{color:'black'}}},scales:{x:{ticks:{color:'black'}},y:{ticks:{color:'black'}}},backgroundColor:'white'}})
+![Benchmark Results](https://quickchart.io/chart?c={type:'bar',data:{labels:['Tokens20','Tokens70','Tokens140','Tokens230'],datasets:[{label:'rawsql-ts',data:[0.029,0.075,0.137,0.239],backgroundColor:'rgba(54,162,235,0.8)',borderColor:'rgba(54,162,235,1)',borderWidth:1},{label:'node-sql-parser',data:[0.210,0.223,0.420,0.871],backgroundColor:'rgba(255,206,86,0.8)',borderColor:'rgba(255,206,86,1)',borderWidth:1},{label:'sql-formatter',data:[0.228,0.547,1.057,1.906],backgroundColor:'rgba(255,99,132,0.8)',borderColor:'rgba(255,99,132,1)',borderWidth:1}]},options:{plugins:{legend:{labels:{color:'black'}}},scales:{x:{ticks:{color:'black'}},y:{ticks:{color:'black'}}},backgroundColor:'white'}}&width=700&height=450)
 
 > [!Note]
 > The "Mean" column represents the average time taken to process a query. Lower values indicate faster performance. For more details, see the [Benchmark](#benchmarks).
 
-## ✨ Browser & CDN Ready!
+## Browser & CDN Ready
 
 You can use rawsql-ts directly in modern browsers via CDN (unpkg/jsdelivr)!
 No Node.js dependencies, no build tools required.
@@ -61,509 +59,277 @@ Just import it like this:
 npm install rawsql-ts
 ```
 
-## Quick Start
-
-```typescript
-import { SelectQueryParser, SqlFormatter } from 'rawsql-ts';
-
-const sql = `SELECT user_id, name FROM users WHERE active = TRUE`;
-const query = SelectQueryParser.parse(sql);
-const formatter = new SqlFormatter();
-const { formattedSql } = formatter.format(query);
-
-console.log(formattedSql);
-// => select "user_id", "name" from "users" where "active" = true
-```
-
 ---
 
-## Formatter Functionality
-
-The `SqlFormatter` class in rawsql-ts is the recommended way to format SQL queries. It provides advanced SQL formatting capabilities, including support for indentation, keyword casing, and line breaks, making it ideal for generating human-readable SQL. 
-
-> [!Note]
-> While the older `Formatter` class is still available for backward compatibility, `SqlFormatter` offers enhanced functionality and is the preferred choice for new projects. `SqlFormatter` is available starting from version 0.7.
-
-### Key Features of SqlFormatter
-
-- **Indentation and Keyword Casing**: Supports customizable indentation and keyword casing (e.g., UPPERCASE, lowercase).
-- **Preset Configurations**: Includes presets for common SQL dialects (MySQL, PostgreSQL, SQL Server, SQLite) to simplify configuration.
-- **Customizable Options**: Allows fine-grained control over formatting styles, such as comma placement, parameter styles, and newline characters.
-- **Parameterized Query Formatting**: Supports anonymous (`?`), indexed (`$1`, `$2`), and named (`:name`, `@name`) parameter styles for compatibility with various database systems.
+## Quick Start
 
-### Preset Configurations (SqlFormatter.PRESETS)
+---
 
-The `SqlFormatter` class provides preset configurations for common SQL dialects. Use these presets to quickly format queries without manually specifying options each time.
+Kickstart your project by dynamically injecting parameters with `SqlParamInjector` for flexible query generation right from the start!
 
 ```typescript
-const formatter = new SqlFormatter({ preset: 'mysql' });
-const { formattedSql } = formatter.format(query);
-console.log(formattedSql);
-```
+import { SqlParamInjector, SqlFormatter } from 'rawsql-ts';
 
-**Preset Details:**
-- `mysql`: Backtick identifier, `?` parameter, no named parameters
-- `postgres`: Double quote identifier, `$` parameter, indexed parameters
-- `sqlserver`: Square bracket identifier, `@` parameter, named parameters
-- `sqlite`: Double quote identifier, `:` parameter, named parameters
+// Define a base SQL query with an alias, using TRUE for boolean conditions
+const baseSql = `SELECT u.user_id, u.user_name, u.email FROM users as u WHERE u.active = TRUE`;
 
-### Customizing SqlFormatter
+// Imagine you have search parameters from a user's input
+const searchParams = {
+  user_name: { like: '%Alice%' }, // Find users whose name contains 'Alice'
+  email: 'specific.email@example.com' // And have a specific email
+};
 
-You can override any preset option as needed. For example, to use variable-style parameters (`${name}`):
+const injector = new SqlParamInjector();
+// Dynamically inject searchParams into the baseSql
+const query = injector.inject(baseSql, searchParams);
 
-```typescript
-const formatter = new SqlFormatter({
-  preset: 'postgres',
-  parameterSymbol: { start: '${', end: '}' },
-});
-const { formattedSql } = formatter.format(query);
+// Format the dynamically generated query (e.g., using PostgreSQL preset)
+const formatter = new SqlFormatter({ preset: 'postgres' }); 
+const { formattedSql, params } = formatter.format(query);
+
+console.log('Dynamically Generated SQL:');
 console.log(formattedSql);
-// => select "user_id", "name" from "users" where "active" = ${active}
+// Expected output (PostgreSQL style):
+// select "u"."user_id", "u"."user_name", "u"."email"
+// from "users" as "u"
+// where "u"."active" = true
+// and "u"."user_name" like :user_name_like
+// and "u"."email" = :email
+
+console.log('\\nParameters:');
+console.log(params);
+// Expected output:
+// { user_name_like: '%Alice%', email: 'specific.email@example.com' }
 ```
 
-### Configurable Options
-
-SqlFormatter supports a wide range of options to customize the output:
-
-- `identifierEscape`: How identifiers are escaped (e.g., `"`, `[`, `` ` ``).
-- `parameterSymbol`: The symbol or pattern for parameters (e.g., `:`, `@`, `?`, or `{ start: '${', end: '}' }`).
-- `parameterStyle`: Controls the parameter style (anonymous, indexed, or named).
-- `indentSize`: Number of spaces or tabs for indentation.
-- `keywordCase`: Casing for SQL keywords (`upper`, `lower`, or `none`).
-- `commaBreak`: Placement of commas (`before` or `after`).
-- `andBreak`: Placement of `AND`/`OR` in conditions (`before` or `after`).
-- `newline`: Specifies the newline character used in the output (e.g., `\n`, `\r\n`, or a single space for compact formatting).
-
-### Parameterized Query Formatting
-
-`SqlFormatter` supports advanced parameterized query formatting for all major SQL dialects. You can output SQL with parameters in three styles:
-
-- **Anonymous** (`?`): For MySQL and similar drivers. Parameters are output as `?` and values are provided as an array.
-- **Indexed** (`$1`, `$2`, ...): For PostgreSQL and compatible drivers. Parameters are output as `$1`, `$2`, ... and values are provided as an array in the correct order.
-- **Named** (`:name`, `@name`): For SQL Server, SQLite, and ORMs. Parameters are output as `:name` or `@name` and values are provided as an object.
-
-The `parameterStyle` option in `SqlFormatter` allows you to control the parameter style, or you can use built-in presets (e.g., `mysql`, `postgres`, `sqlserver`, `sqlite`) to apply the correct style automatically.
+---
 
-### Usage Example
+## SelectQueryParser Features
 
-#### Using a Preset
+rawsql-ts provides robust parsers for `SELECT`, `INSERT`, and `UPDATE` statements, automatically handling SQL comments and providing detailed error messages. By converting SQL into a generic Abstract Syntax Tree (AST), it enables a wide variety of transformation processes.
 
 ```typescript
-import { SqlFormatter } from 'rawsql-ts';
+import { SelectQueryParser } from 'rawsql-ts';
 
-const sql = `SELECT user_id, name FROM users WHERE active = TRUE`;
+const sql = `SELECT id, name FROM products WHERE category = 'electronics'`;
 const query = SelectQueryParser.parse(sql);
-const formatter = new SqlFormatter({ preset: 'postgres' });
-const { formattedSql } = formatter.format(query);
-console.log(formattedSql);
-/*
-select "user_id", "name" from "users" where "active" = true
-*/
+// query object now holds the AST of the SQL
 ```
 
-#### Using Custom Configuration
+For more details on `SelectQueryParser`, see the [SelectQueryParser Usage Guide](./docs/usage-guides/class-SelectQueryParser-usage-guide.md).
 
-```typescript
-import { SqlFormatter } from 'rawsql-ts';
+---
 
-const sql = `SELECT user_id, name FROM users WHERE active = TRUE`;
-const query = SelectQueryParser.parse(sql);
-const formatter = new SqlFormatter({
-  identifierEscape: { start: '`', end: '`' },
-  parameterSymbol: '?',
-  parameterStyle: 'anonymous',
-  indentSize: 2,
-  keywordCase: 'upper',
-  newline: '\r\n',
-  commaBreak: 'before', // Specify the "before comma" option
-});
-const { formattedSql } = formatter.format(query);
-console.log(formattedSql);
-/*
-SELECT
-  `user_id`
-  , `name`
-FROM
-  `users`
-WHERE
-  `active` = ?
-*/
-```
+## SqlFormatter Features
 
-#### Parameterized Query Output
+The `SqlFormatter` class is the recommended way to format SQL queries, offering advanced capabilities like indentation, keyword casing, and multi-line formatting.
+It also allows for detailed style customization. For example, you can define your own formatting rules:
 
 ```typescript
 import { SelectQueryParser, SqlFormatter } from 'rawsql-ts';
 
-const sql = 'SELECT * FROM users WHERE id = :id AND status = :status';
-const query = SelectQueryParser.parse(sql);
-query.setParameter('id', 123);
-query.setParameter('status', 'active');
-
-const formatter = new SqlFormatter({ parameterStyle: 'named' });
-const { formattedSql, params } = formatter.format(query);
-
-console.log(formattedSql);
-// => select * from "users" where "id" = :id and "status" = :status
-console.log(params);
-// => { id: 123, status: 'active' }
-```
-
-For anonymous or indexed styles, simply change the `parameterStyle` option:
+const customStyle = {
+  identifierEscape: {
+    start: "",
+    end: ""
+  },
+  parameterSymbol: ":",
+  parameterStyle: "named",
+  indentSize: 4,
+  indentChar: " ",
+  newline: "\n",
+  keywordCase: "lower",
+  commaBreak: "before",
+  andBreak: "before"
+};
 
-```typescript
-const formatter = new SqlFormatter({ parameterStyle: 'anonymous' });
-// formattedSql: 'select * from "users" where "id" = ? and "status" = ?'
-// params: [123, 'active']
+const sqlToFormat = `SELECT u.user_id, u.user_name FROM users as u WHERE status = :active ORDER BY created_at DESC;`;
+const queryToFormat = SelectQueryParser.parse(sqlToFormat);
+const customFormatter = new SqlFormatter(customStyle);
+const { formattedSql: customFormattedSql } = customFormatter.format(queryToFormat);
 
-const formatterIndexed = new SqlFormatter({ parameterStyle: 'indexed' });
-// formattedSql: 'select * from "users" where "id" = $1 and "status" = $2'
-// params: [123, 'active']
+console.log(customFormattedSql);
+/*
+select
+    u.user_id
+    , u.user_name
+from
+    users as u
+where
+    status = :active
+order by
+    created_at desc;
+*/
 ```
 
-`SqlFormatter` ensures parameter indexes are assigned correctly, even for complex queries with CTEs, subqueries, or set operations. This makes it easy to build safe, maintainable, and portable SQL in TypeScript.
-
-> [!Tip]
-> Use named parameters in your source code for better readability and maintainability. You can always output the final SQL and parameters in the style required by your database client (e.g., anonymous or indexed) at formatting time.
-
----
-
-## Main Parser Features
-
-- All parsers automatically remove SQL comments before parsing.
-- Detailed error messages are provided for all parsing errors.
-- Highly accurate and advanced tokenization is used for robust SQL analysis.
-
-> [!Note]
-> All parsers in rawsql-ts have been tested with PostgreSQL syntax, but they are capable of parsing any generic SQL statement that does not use a DBMS-specific dialect.
-
-- **SelectQueryParser**  
-  The main class for converting SELECT and VALUES statements into AST. Fully supports CTEs (WITH), UNION/INTERSECT/EXCEPT, subqueries, and PostgreSQL-style syntax.
-  - `parse(sql: string): SelectQuery`  
-    Converts a SQL string to an AST. Throws an exception on error.
-  - In this library, a "select query" is represented as one of the following types:
-    - `SimpleSelectQuery`: A standard SELECT statement with all major clauses (WHERE, GROUP BY, JOIN, etc.)
-    - `BinarySelectQuery`: A set operation query such as UNION, INTERSECT, or EXCEPT
-    - `ValuesQuery`: An inline VALUES table (e.g., `VALUES (1, 'a'), (2, 'b')`)
-
-- **InsertQueryParser**  
-  The main class for parsing `INSERT INTO` statements and converting them into AST. Supports PostgreSQL-style INSERT with or without column lists, as well as `INSERT ... SELECT` and `INSERT ... VALUES` forms.
-  - `parse(sql: string): InsertQuery`  
-    Converts an INSERT SQL string to an AST. Throws an exception on error.
-
-- **UpdateQueryParser**  
-  The main class for parsing `UPDATE` statements and converting them into AST. Supports PostgreSQL-style UPDATE with optional CTE (WITH clause), table alias, SET, WHERE, FROM, and RETURNING clauses.
-  - `parse(sql: string): UpdateQuery`  
-    Converts an UPDATE SQL string to an AST. Throws an exception on error.
+For more details, see the [SqlFormatter Usage Guide](./docs/usage-guides/class-SqlFormatter-usage-guide.md).
 
 ---
 
-## 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
-  - `appendWhereExpr` to add a WHERE condition using the column's SQL expression (see below)
-  - `overrideSelectItemExpr` to override a SELECT item using its SQL expression (see below)
-  - `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
----
+## SqlParamInjector Features
 
-## Advanced Expression-based Methods
+The `SqlParamInjector` class revolutionizes how you build dynamic search queries. Instead of manually constructing different SQL statements for various search conditions, you simply provide a fixed base SQL and a state object. `SqlParamInjector` then dynamically injects parameters and automatically generates the optimal WHERE conditions.
 
-### appendWhereExpr
-`appendWhereExpr` is a highly important feature that enables you to add WHERE conditions using the SQL expression of a column, regardless of whether it is a direct column, an alias, a table alias, or even a calculated expression.
-
-- **Basic Column**
-  - SQL: `select amount from sales`
-  - API: `query.appendWhereExpr('amount', expr => `${expr} > 100`)`
-  - Result: `where amount > 100`
-
-- **Alias**
-  - SQL: `select fee as amount from sales`
-  - API: `query.appendWhereExpr('amount', expr => `${expr} > 100`)`
-  - Result: `where fee > 100`
-
-- **Table Alias**
-  - SQL: `select s.fee as amount from sales as s`
-  - API: `query.appendWhereExpr('amount', expr => `${expr} > 100`)`
-  - Result: `where s.fee > 100`
-
-- **Expression**
-  - SQL: `select quantity * pack_size as amount from sales`
-  - API: `query.appendWhereExpr('amount', expr => `${expr} > 100`)`
-  - Result: `where quantity * pack_size > 100`
-
-As long as the column is named (or aliased) as `amount`, `appendWhereExpr` will detect and use the correct SQL expression for the WHERE clause—even if it is a complex calculation or uses table aliases.
+Key benefits include:
+- **Simplified Query Management**: Prepare a single base SQL; `SqlParamInjector` handles the variations.
+- **Effortless Optimal Queries**: Just pass a state object, and it generates a highly efficient query.
+- **Performance-Oriented**: Conditions are intelligently inserted as close to the data source as possible, significantly improving query performance by filtering data early.
+- **Zero Conditional Logic in Code**: Forget writing complex IF statements in your application code to handle different filters.
+- **Enhanced SQL Reusability**: Your base SQL remains clean and can be reused across different scenarios with varying search criteria.
 
 ```typescript
-// Works for any alias, table alias, or expression!
-query.appendWhereExpr('amount', expr => `${expr} > 100`);
-```
+import { SqlParamInjector, SqlFormatter } from 'rawsql-ts';
 
-#### Upstream Query Support
+const sql = `SELECT u.user_id, u.user_name FROM users as u WHERE u.active = TRUE`;
+const injector = new SqlParamInjector();
+// Inject parameters and generate WHERE conditions
+const injectedQuery = injector.inject(sql, { user_id: 42, user_name: 'Alice' });
 
-`Upstream Query Support` is a powerful extension of `appendWhereExpr` that allows you to add WHERE conditions to all relevant upstream queries that provide a specific column, regardless of the query structure. This means you can target columns defined in subqueries, CTEs (WITH clauses), or even branches of UNION/INTERSECT/EXCEPT, and the condition will be automatically inserted at the correct place in the SQL tree.
+const formatter = new SqlFormatter();
+const { formattedSql, params } = formatter.format(injectedQuery);
 
-**What does this mean in practice?**
-- If the column is defined in a subquery, the WHERE condition is added inside that subquery.
-- If the column is defined in a CTE (WITH clause), the WHERE condition is added inside the CTE.
-- If the column is provided by multiple upstream queries (e.g., UNION branches), the condition is added to all relevant branches.
-- You do not need to know or traverse the query structure yourself—just specify the column name, and `appendWhereExpr` with `{ upstream: true }` will do the rest.
+console.log(formattedSql);
+// Output: select "u"."user_id", "u"."user_name" from "users" as "u" where "u"."active" = true and "u"."user_id" = :user_id and "u"."user_name" = :user_name
+console.log(params);
+// Output: { user_id: 42, user_name: 'Alice' }
+```
 
-##### Example: Filtering a CTE
+For more details, see the [SqlParamInjector Usage Guide](./docs/usage-guides/class-SqlParamInjector-usage-guide.md).
 
-```typescript
-const query = SelectQueryParser.parse(`
-  WITH temp_sales AS (
-    SELECT id, amount, date FROM sales WHERE date >= '2024-01-01'
-  )
-  SELECT * FROM temp_sales
-`) as SimpleSelectQuery;
+---
 
-// Add a filter to the CTE using upstream support
-query.appendWhereExpr('amount', expr => `${expr} > 100`, { upstream: true });
+## PostgreJsonQueryBuilder Features
 
-const sql = new SqlFormatter().format(query).formattedSql;
-console.log(sql);
-// => with "temp_sales" as (select "id", "amount", "date" from "sales" where "date" >= '2024-01-01' and "amount" > 100) select * from "temp_sales"
-```
+The `PostgreJsonQueryBuilder` class transforms relational SQL queries into PostgreSQL JSON queries that return hierarchical JSON structures. It automatically handles complex relationships between entities and generates optimized Common Table Expressions (CTEs) for efficient JSON aggregation, making it perfect for building APIs, reports, and data exports.
 
-##### Example: Filtering All Branches of a UNION
+Key benefits include:
+- **Hierarchical JSON Generation**: Transforms flat relational data into nested JSON objects and arrays
+- **Automatic CTE Management**: Generates optimized CTEs with proper dependency ordering
+- **Flexible Relationship Types**: Supports both object (0..1) and array (1..N) relationships
+- **NULL Handling**: Properly represents missing relationships as NULL instead of empty objects
+- **Performance Optimized**: Uses depth-based processing and JSONB for optimal PostgreSQL performance
+- **Zero Manual Serialization**: Eliminates the need for manual object mapping and JSON construction
 
 ```typescript
-const query = SelectQueryParser.parse(`
-  WITH sales_transactions AS (
-    SELECT transaction_id, customer_id, amount, transaction_date FROM sales_schema.transactions WHERE transaction_date >= CURRENT_DATE - INTERVAL '90 days'
-  ),
-  support_transactions AS (
-    SELECT support_id AS transaction_id, user_id AS customer_id, fee AS amount, support_date AS transaction_date FROM support_schema.support_fees WHERE support_date >= CURRENT_DATE - INTERVAL '90 days'
-  )
-  SELECT * FROM (
-    SELECT * FROM sales_transactions
-    UNION ALL
-    SELECT * FROM support_transactions
-  ) d
-  ORDER BY transaction_date DESC
+import { SelectQueryParser, PostgreJsonQueryBuilder } from 'rawsql-ts';
+
+// Parse your base SQL query
+const baseQuery = SelectQueryParser.parse(`
+    SELECT o.order_id, o.order_date, c.customer_name, i.product_name, i.quantity
+    FROM orders o
+    LEFT JOIN customers c ON o.customer_id = c.customer_id  
+    LEFT JOIN order_items i ON o.order_id = i.order_id
 `) as SimpleSelectQuery;
 
-// Add a filter to all upstream queries that provide 'amount'
-query.appendWhereExpr('amount', expr => `${expr} > 100`, { upstream: true });
+// Define JSON mapping configuration
+const mapping = {
+    rootName: "order",
+    rootEntity: { id: "order", name: "Order", columns: { "id": "order_id", "date": "order_date" }},
+    nestedEntities: [
+        { id: "customer", parentId: "order", propertyName: "customer", relationshipType: "object", 
+          columns: { "name": "customer_name" }},
+        { id: "items", parentId: "order", propertyName: "items", relationshipType: "array",
+          columns: { "product": "product_name", "qty": "quantity" }}
+    ],
+    useJsonb: true
+};
 
-const sql = new SqlFormatter().format(query).formattedSql;
-console.log(sql);
-// => with "sales_transactions" as (select ... where ... and "amount" > 100),
-//        "support_transactions" as (select ... where ... and "fee" > 100)
-//    select * from (... union all ...) as "d" order by "transaction_date" desc
+// Transform to JSON query
+const builder = new PostgreJsonQueryBuilder();
+const jsonQuery = builder.buildJson(baseQuery, mapping);
+// Returns optimized PostgreSQL query with CTEs that produces:
+// [{ "id": 1, "date": "2024-01-15", "customer": {"name": "John"}, "items": [{"product": "Widget", "qty": 2}] }]
 ```
 
-### appendWhereExpr Use Cases
-
-`appendWhereExpr` is especially useful in the following scenarios:
-
-- **Dynamic Search Conditions for Complex Reports**  
-  Easily inject arbitrary search filters into deeply nested or highly complex queries, such as those used in reporting or analytics dashboards. This enables flexible, user-driven filtering without manual SQL string manipulation.
-
-- **Performance-Critical Query Construction**  
-  Build high-performance queries by programmatically adding WHERE conditions only when needed, ensuring that unnecessary filters are not included and that the generated SQL remains as efficient as possible.
-
-- **Generic Access Control and Security Filters**  
-  Apply reusable access control or security-related WHERE clauses (e.g., tenant isolation, user-based restrictions) across all relevant queries, regardless of their internal structure. This helps enforce consistent data access policies throughout your application.
-
-> [!TIP] 
-> Upstream Query Support is especially useful for large, complex SQL with multiple layers of subqueries, CTEs, or set operations. You can add filters or conditions without worrying about the internal structure—just specify the column name!
->
-> You can focus on developing and maintaining RawSQL itself, without being bothered by troublesome variable search conditions.
+For more details, see the [PostgreJsonQueryBuilder Usage Guide](./docs/usage-guides/class-PostgreJsonQueryBuilder-usage-guide.md).
 
 ---
 
-### overrideSelectItemExpr
-Overrides a SELECT item using its SQL expression. The callback receives the original SQL expression as a string and returns a new SQL string.
-
-```typescript
-// Override the SELECT item 'journal_date' to use greatest(journal_date, DATE '2025-01-01')
-query.overrideSelectItemExpr('journal_date', expr => `greatest(${expr}, DATE '2025-01-01')`);
-```
-
----
+## SqlSchemaValidator Features
 
-## AST Transformer Features
-
-A suite of utilities for transforming and analyzing SQL ASTs.
-
-### Main Transformers
-
-- **SqlFormatter**
-  Converts ASTs to formatted SQL strings. Handles identifier escaping. Supports both single-line (compact) and multi-line (formatted) styles.
-- **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.
-
-- **QueryBuilder**  
-  Converts any SELECT/UNION/VALUES query into a standard SimpleSelectQuery. Handles subquery wrapping and automatic column name generation.
-  Supports CREATE TABLE ... AS SELECT ... conversion:
-  - `QueryBuilder.buildCreateTableQuery(query, tableName, isTemporary?)` creates a `CreateTableQuery` from any SELECT query.
-  Supports combining multiple queries:
-  - `QueryBuilder.buildBinaryQuery(queries, operator)` combines an array of SelectQuery objects into a single BinarySelectQuery using the specified set operator (e.g., 'union', 'intersect', 'except').
-  Supports INSERT and UPDATE statement generation from SELECT:
-  - `QueryBuilder.buildInsertQuery(selectQuery, tableName)` creates an `InsertQuery` from a `SimpleSelectQuery` and a target table name.  
-    The columns are inferred from the select query. Throws if columns cannot be determined.
-  - `QueryBuilder.buildUpdateQuery(selectQuery, selectSourceName, updateTableExprRaw, primaryKeys)` creates an `UpdateQuery` from a `SimpleSelectQuery`, the source alias, the update target table, and primary key(s).  
-    This generates an UPDATE ... SET ... FROM ... WHERE ... statement using the SELECT as the value source. Throws if PK columns are missing or ambiguous.
-
-- **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[];
-  ```
-
-> [!NOTE]
-> As of version 0.4.0-beta, the class previously named `QueryConverter` has been renamed to `QueryBuilder`, and its methods have been updated for consistency. The new `buildBinaryQuery` method was also introduced, allowing you to combine multiple `SelectQuery` objects into a single set operation query. These are breaking changes. If you were using `QueryConverter` in earlier versions, please update your code to use `QueryBuilder` and the new method names (e.g., `buildCreateTableQuery`, `buildBinaryQuery`).
+The `SqlSchemaValidator` class helps ensure your SQL queries are valid against a predefined database schema. It can extract schema information about the physical tables your SQL query depends on. By comparing this extracted information with your defined schema (e.g., a schema definition class), you can statically verify the query's behavior. This enables you to perform regression testing as part of your unit tests when schema definitions change, ensuring that your queries remain compatible.
 
----
+It checks if the tables and columns referenced in your query actually exist in your schema, and it understands table aliases. If there's a problem, it gives you a clear error message telling you what's wrong and where.
 
-## Usage Example
+Key benefits include:
+- **Schema Validation**: Verifies SQL queries against your database schema.
+- **Table and Column Verification**: Confirms the existence of tables and columns used in the query.
+- **Alias Aware**: Correctly resolves table aliases.
+- **Clear Error Reporting**: Provides descriptive error messages for easy debugging.
+- **Static Analysis**: Allows comparison of SQL-derived schema information with predefined schema definitions.
+- **Automated Regression Testing**: Facilitates unit testing for schema change impacts on queries.
 
 ```typescript
-import { TableColumnResolver, SelectQueryParser, SelectableColumnCollector, SelectValueCollector, TableSourceCollector, SqlFormatter } from 'rawsql-ts';
+import { SelectQueryParser, SqlSchemaValidator } from 'rawsql-ts';
 
-// TableColumnResolver example
-const resolver: TableColumnResolver = (tableName) => {
-    if (tableName === 'users') return ['user_id', 'user_name', 'email'];
-    if (tableName === 'posts') return ['post_id', 'user_id', 'title', 'content'];
-    return [];
+// Define your database schema
+const schema = {
+  users: ['user_id', 'user_name', 'email', 'status'],
+  orders: ['order_id', 'user_id', 'order_date', 'total_amount']
 };
 
-const sql = `SELECT u.*, p.title as post_title FROM users u INNER JOIN posts p ON u.user_id = p.user_id`;
-const query = SelectQueryParser.parse(sql);
-const formatter = new SqlFormatter();
-
-// Collects information from the SELECT clause.
-// To expand wildcards, you must specify a TableColumnResolver.
-const selectValueCollector = new SelectValueCollector(resolver);
-const selectValues = selectValueCollector.collect(query);
-// Log the name and formatted value of each select value
-console.log('Select values:');
-selectValues.forEach(val => {
-    console.log(`  name: ${val.name}, value: ${formatter.format(val.value).formattedSql}`);
-});
-/*
-Select values:
-  name: post_title, value: "p"."title"
-  name: user_id, value: "u"."user_id"
-  name: user_name, value: "u"."user_name"
-  name: email, value: "u"."email"
-*/
+const validator = new SqlSchemaValidator(schema);
+
+// Example: Validate a SELECT query
+const validSql = 'SELECT u.user_id, u.user_name FROM users as u WHERE u.status = \'active\'';
+const queryToValidate = SelectQueryParser.parse(validSql);
+
+try {
+  validator.validate(queryToValidate);
+  console.log('Query is valid against the schema.');
+} catch (error) {
+  console.error('Schema validation failed:', error.message);
+}
+
+// Example: Validate a query with a non-existent column
+const invalidSql = 'SELECT user_id, non_existent_column FROM users';
+const invalidQuery = SelectQueryParser.parse(invalidSql);
+
+try {
+  validator.validate(invalidQuery);
+} catch (error) {
+  console.error('Schema validation error for non-existent column:', error.message);
+  // Expected output: Validation failed: Column 'non_existent_column' not found in table 'users'.
+}
 ```
 
-```typescript
-// Collects selectable columns from the FROM/JOIN clauses.
-// You can get accurate information by specifying a TableColumnResolver.
-// If omitted, the information will be inferred from the query content.
-const selectableColumnCollector = new SelectableColumnCollector(resolver);
-const selectableColumns = selectableColumnCollector.collect(query);
-// Log detailed info for each selectable column
-console.log('Selectable columns:');
-selectableColumns.forEach(val => {
-    console.log(`  name: ${val.name}, value: ${formatter.format(val.value).formattedSql}`);
-});
-/*
-Selectable columns:
-  name: post_title, value: "p"."title"
-  name: user_id, value: "u"."user_id"
-  name: user_name, value: "u"."user_name"
-  name: email, value: "u"."email"
-  name: post_id, value: "p"."post_id"
-  name: title, value: "p"."title"
-  name: content, value: "p"."content"
-*/
-```
-
-```typescript
-// Create Table from SELECT Example
-import { QueryBuilder, SelectQueryParser, SqlFormatter } from 'rawsql-ts';
-
-const select = SelectQueryParser.parse('SELECT id, name FROM users');
-const create = QueryBuilder.buildCreateTableQuery(select, 'my_table');
-const sqlCreate = new SqlFormatter().format(create).formattedSql;
-console.log(sqlCreate);
-// => create table "my_table" as select "id", "name" from "users"
-
-const createTemp = QueryBuilder.buildCreateTableQuery(select, 'tmp_table', true);
-const sqlTemp = new SqlFormatter().format(createTemp).formattedSql;
-console.log(sqlTemp);
-// => create temporary table "tmp_table" as select "id", "name" from "users"
-```
-
-```typescript
-// Retrieves physical table sources.
-const tableSourceCollector = new TableSourceCollector();
-const sources = tableSourceCollector.collect(query);
-// Log detailed info for each source
-console.log('Sources:');
-sources.forEach(src => {
-    console.log(`  name: ${src.getSourceName()}`);
-});
-/*
-TableSources:
-  name: users
-  name: posts
-*/
-```
+For more details on `SqlSchemaValidator`, see the [SqlSchemaValidator Usage Guide](./docs/usage-guides/class-SqlSchemaValidator-usage-guide.md).
 
 ---
 
-## Advanced Example: Table Join
+## QueryBuilder Features
 
-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.
+`QueryBuilder` is a powerful utility that enhances the management and generation of SQL modification queries (such as `INSERT` or `UPDATE`) by leveraging select queries. This approach significantly improves the maintainability of complex data manipulation logic. It allows for the conversion of select queries into corresponding update-type queries, streamlining development and ensuring consistency.
 
 ```typescript
-import { SelectQueryParser, SqlFormatter, 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');
-
-const formatter = new SqlFormatter();
-const formattedSql = formatter.format(query).formattedSql;
-
-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
+import { SelectQueryParser, QueryBuilder, SqlFormatter, QueryNormalizer } from 'rawsql-ts';
+
+// Example: Convert a SELECT query to an UPDATE query
+const selectSourceSql = 'SELECT id, new_email AS email, last_login FROM user_updates_source WHERE needs_update = TRUE';
+// QueryBuilder.buildUpdateQuery expects a SimpleSelectQuery as input.
+// If your source is a complex query (e.g. with UNIONs or CTEs), normalize it first.
+const normalizedSelectQuery = QueryNormalizer.normalize(SelectQueryParser.parse(selectSourceSql));
+
+// Define the target table for the UPDATE and the primary key(s) for joining
+const targetTable = 'users';
+const primaryKeys = ['id']; // Column(s) to match records between source and target
+
+const updateQuery = QueryBuilder.buildUpdateQuery(
+  normalizedSelectQuery,
+  'd', // Alias of the source query in the FROM clause
+  targetTable,
+  primaryKeys
+);
+
+const formatter = new SqlFormatter({ preset: 'postgres' }); // Using postgres preset for clarity
+const { formattedSql: updateSql } = formatter.format(updateQuery);
+
+console.log(updateSql);
+// Example output (actual output depends on the SQL dialect and specific query structure):
+// update "users" set "email" = "d"."email", "last_login" = "d"."last_login" from (SELECT id, new_email AS email, last_login FROM user_updates_source WHERE needs_update = TRUE) as "d" where "users"."id" = "d"."id"
 ```
 
-**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
+For more details on `QueryBuilder`, see the [QueryBuilder Usage Guide](./docs/usage-guides/class-QueryBuilder-usage-guide.md).
 
 ---