rawsql-ts 0.10.9-beta → 0.11.0-beta

package/README.md

@@ -23,6 +23,8 @@ It is designed for extensibility and advanced SQL analysis, with initial focus o
 - 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
+- **JSON-to-TypeScript type transformation** - Automatically convert JSON-ified SQL results (dates as strings, BigInts) back to proper TypeScript types with configurable transformation rules
+- **All-in-one dynamic query building with `DynamicQueryBuilder`** - combines filtering, sorting, pagination, and JSON serialization in a single, type-safe interface
 - Dynamic SQL parameter injection for building flexible search queries with `SqlParamInjector` (supports like, ilike, in, any, range queries, OR/AND conditions and more)
 - Dynamic ORDER BY clause injection with `SqlSortInjector` for flexible sorting with support for ASC/DESC, NULLS positioning, and append mode
 - Dynamic LIMIT/OFFSET pagination injection with `SqlPaginationInjector` for efficient data pagination with page-based and offset-based support
@@ -43,14 +45,14 @@ Just import it like this:
 ```html
 <!-- Always get the latest version -->
 <script type="module">
-  import { parse } from "https://unpkg.com/rawsql-ts/dist/esm/index.js";
+  import { parse } from "https://unpkg.com/rawsql-ts/dist/esm/index.min.js";
 </script>
 ```
 
 ```html
 <!-- Pin a specific version for stability -->
 <script type="module">
-  import { parse } from "https://unpkg.com/rawsql-ts@0.1.0-beta.12/dist/esm/index.js";
+  import { parse } from "https://unpkg.com/rawsql-ts@0.10.9-beta/dist/esm/index.min.js";
 </script>
 ```
 
@@ -66,63 +68,126 @@ npm install rawsql-ts
 
 ## Quick Start
 
-Kickstart your project by dynamically injecting parameters with `SqlParamInjector` for flexible query generation right from the start!
+Experience the power of rawsql-ts with `DynamicQueryBuilder` - build complex queries with filtering, sorting, pagination, and JSON serialization in one go!
 
 ```typescript
-import { SqlParamInjector, SqlFormatter } from 'rawsql-ts';
-
-// Define a base SQL query with an alias
-const baseSql = `SELECT u.user_id, u.user_name, u.email, u.phone FROM users as u WHERE u.active = TRUE`;
-
-// Search parameters with OR conditions and AND combination
-const searchParams = {
-  name_or_email: {
-    or: [
-      { column: 'user_name', ilike: '%alice%' },
-      { column: 'email', ilike: '%alice%' }
-    ]
+import { DynamicQueryBuilder, SqlFormatter } from 'rawsql-ts';
+
+// Start with a simple base SQL
+const baseSql = 'SELECT id, name, email, created_at FROM users WHERE active = true';
+
+// Build a complete dynamic query with all features
+const builder = new DynamicQueryBuilder();
+const query = builder.buildQuery(baseSql, {
+  // Dynamic filtering
+  filter: { 
+    status: 'premium', 
+    created_at: { '>': '2024-01-01' } 
   },
-  phone: { like: '%080%' }  // AND condition
-};
-
-const injector = new SqlParamInjector();
-// Dynamically inject searchParams into the baseSql
-const query = injector.inject(baseSql, searchParams);
+  // Dynamic sorting
+  sort: { 
+    created_at: { desc: true }, 
+    name: { asc: true } 
+  },
+  // Dynamic pagination
+  paging: { 
+    page: 2, 
+    pageSize: 10 
+  },
+  // JSON serialization (optional)
+  serialize: {
+    rootName: 'user',
+    rootEntity: { 
+      id: 'user', 
+      name: 'User', 
+      columns: { id: 'id', name: 'name', email: 'email', createdAt: 'created_at' } 
+    },
+    nestedEntities: []
+  }
+});
 
-// Format the dynamically generated query
-const formatter = new SqlFormatter({ preset: 'postgres' }); 
+// Format and execute
+const formatter = new SqlFormatter();
 const { formattedSql, params } = formatter.format(query);
 
 console.log('Generated SQL:');
 console.log(formattedSql);
-// Output:
-// select "u"."user_id", "u"."user_name", "u"."email", "u"."phone"
-// from "users" as "u"
-// where "u"."active" = true
-//   and ("u"."user_name" ilike :name_or_email_or_0_ilike
-//        or "u"."email" ilike :name_or_email_or_1_ilike)
-//   and "u"."phone" like :phone_like
+// Output: Optimized PostgreSQL JSON query with filtering, sorting, and pagination
 
 console.log('Parameters:');
 console.log(params);
-// Output: { name_or_email_or_0_ilike: '%alice%', name_or_email_or_1_ilike: '%alice%', phone_like: '%080%' }
+// Output: { status: 'premium', created_at_gt: '2024-01-01' }
 ```
 
 ---
 
-## SelectQueryParser Features
+## SelectQueryParser & Query Types
 
 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.
 
+### Query Type Overview
+
+The parser returns different query types based on SQL structure:
+
+- **`SimpleSelectQuery`**: Single SELECT statement with comprehensive manipulation API
+- **`BinarySelectQuery`**: Combined queries using UNION, INTERSECT, EXCEPT operators
+- **`ValuesQuery`**: VALUES clause queries for data insertion or testing
+- **`SelectQuery`**: Base interface implemented by all SELECT query classes
+
 ```typescript
 import { SelectQueryParser } from 'rawsql-ts';
 
-const sql = `SELECT id, name FROM products WHERE category = 'electronics'`;
-const query = SelectQueryParser.parse(sql);
-// query object now holds the AST of the SQL
+// Returns SimpleSelectQuery
+const simpleQuery = SelectQueryParser.parse('SELECT id, name FROM products WHERE category = \'electronics\'');
+
+// Returns BinarySelectQuery  
+const unionQuery = SelectQueryParser.parse('SELECT id, name FROM products UNION SELECT id, name FROM archived_products');
+
+// Returns ValuesQuery
+const valuesQuery = SelectQueryParser.parse('VALUES (1, \'Alice\'), (2, \'Bob\')');
+```
+
+### SimpleSelectQuery - Rich Programmatic API
+
+`SimpleSelectQuery` provides extensive methods for programmatic query building and manipulation:
+
+**Dynamic Condition Building:**
+- `appendWhereExpr(columnName, exprBuilder)` - Add conditions by column name with upstream injection support
+- `appendWhereRaw()`, `appendHavingRaw()` - Append raw SQL conditions
+- `setParameter(name, value)` - Manage named parameters directly on the query object
+
+**Query Composition:**
+- `toUnion()`, `toIntersect()`, `toExcept()` - Combine with other queries
+- `innerJoin()`, `leftJoin()`, `rightJoin()` - Add JOIN clauses programmatically
+- `appendWith()` - Add Common Table Expressions (CTEs)
+
+**Advanced Features:**
+- Column-aware condition injection that resolves aliases and expressions
+- Parameter management with validation and type safety
+- Subquery wrapping with `toSource(alias)` for complex compositions
+
+```typescript
+import { SelectQueryParser } from 'rawsql-ts';
+
+const query = SelectQueryParser.parse('SELECT id, salary * 1.1 AS adjusted_salary FROM employees');
+
+// Add condition targeting the calculated column
+query.appendWhereExpr('adjusted_salary', expr => `${expr} > 50000`);
+
+// Set parameters directly on the query
+query.setParameter('dept_id', 123);
+
+// Add JOINs programmatically
+query.leftJoinRaw('departments', 'd', 'department_id');
+
+// Combine with another query
+const adminQuery = SelectQueryParser.parse('SELECT id, salary FROM admins');
+const combinedQuery = query.toUnion(adminQuery);
 ```
 
-For more details on `SelectQueryParser`, see the [SelectQueryParser Usage Guide](./docs/usage-guides/class-SelectQueryParser-usage-guide.md).
+For comprehensive API documentation and advanced examples, see the [SimpleSelectQuery Usage Guide](../../docs/usage-guides/class-SimpleSelectQuery-usage-guide.md).
+
+For SelectQueryParser details, see the [SelectQueryParser Usage Guide](../../docs/usage-guides/class-SelectQueryParser-usage-guide.md).
 
 ---
 
@@ -168,7 +233,7 @@ order by
 */
 ```
 
-For more details, see the [SqlFormatter Usage Guide](./docs/usage-guides/class-SqlFormatter-usage-guide.md).
+For more details, see the [SqlFormatter Usage Guide](../../docs/usage-guides/class-SqlFormatter-usage-guide.md).
 
 ---
 
@@ -202,7 +267,7 @@ console.log(params);
 // Output: { user_id: 42, user_name: 'Alice' }
 ```
 
-For more details, see the [SqlParamInjector Usage Guide](./docs/usage-guides/class-SqlParamInjector-usage-guide.md).
+For more details, see the [SqlParamInjector Usage Guide](../../docs/usage-guides/class-SqlParamInjector-usage-guide.md).
 
 ---
 
@@ -249,7 +314,7 @@ const newSortedQuery = injector.inject(cleanQuery, { name: { desc: true } });
 // Result: SELECT id, name FROM users ORDER BY name DESC
 ```
 
-For more details, see the [SqlSortInjector Usage Guide](./docs/usage-guides/class-SqlSortInjector-usage-guide.md).
+For more details, see the [SqlSortInjector Usage Guide](../../docs/usage-guides/class-SqlSortInjector-usage-guide.md).
 
 ---
 
@@ -305,7 +370,72 @@ query = new SqlPaginationInjector().inject(query, { page: 3, pageSize: 15 });
 // Result: Filtered, sorted, and paginated query ready for execution
 ```
 
-For more details, see the [SqlPaginationInjector Usage Guide](./docs/usage-guides/class-SqlPaginationInjector-usage-guide.md).
+For more details, see the [SqlPaginationInjector Usage Guide](../../docs/usage-guides/class-SqlPaginationInjector-usage-guide.md).
+
+---
+
+## DynamicQueryBuilder Features
+
+The `DynamicQueryBuilder` class is a powerful, all-in-one solution that combines SQL parsing with dynamic condition injection (filtering, sorting, pagination, and JSON serialization). It provides a unified interface for building complex queries without the need to manually chain multiple injectors, making it ideal for modern web applications that require flexible, dynamic query generation.
+
+Key benefits include:
+- **Unified Interface**: Single class that combines filtering, sorting, pagination, and JSON serialization
+- **Framework-Agnostic**: Pure JavaScript/TypeScript with no file system dependencies
+- **Composable Architecture**: Internally uses specialized injectors in optimal order for performance
+- **Type-Safe**: Full TypeScript support with strongly typed options and return values
+- **Performance Optimized**: Applies conditions in the most efficient order (filter → sort → paginate → serialize)
+- **Easy Testing**: No external dependencies make unit testing straightforward
+
+```typescript
+import { DynamicQueryBuilder, SqlFormatter } from 'rawsql-ts';
+
+// Create a builder instance
+const builder = new DynamicQueryBuilder();
+
+// Build a complete dynamic query with all features
+const baseQuery = 'SELECT id, name, email, created_at FROM users WHERE active = true';
+const options = {
+  filter: { 
+    status: 'premium',
+    created_at: { min: '2024-01-01' }  // Range filter
+  },
+  sort: { 
+    created_at: { desc: true, nullsLast: true },
+    name: { asc: true }
+  },
+  paging: { page: 2, pageSize: 20 },
+  serialize: {
+    rootName: 'users',
+    rootEntity: {
+      id: 'user',
+      name: 'User',
+      columns: { id: 'id', name: 'name', email: 'email', created: 'created_at' }
+    },
+    nestedEntities: []
+  }
+};
+
+const dynamicQuery = builder.buildQuery(baseQuery, options);
+
+const formatter = new SqlFormatter();
+const { formattedSql, params } = formatter.format(dynamicQuery);
+
+console.log(formattedSql);
+// Output: Complex JSON query with all conditions applied
+console.log(params);
+// Output: { status: 'premium', created_at_min: '2024-01-01', paging_limit: 20, paging_offset: 20 }
+
+// Convenience methods for specific use cases
+const filteredOnly = builder.buildFilteredQuery(baseQuery, { name: 'Alice' });
+const sortedOnly = builder.buildSortedQuery(baseQuery, { created_at: { desc: true } });
+const paginatedOnly = builder.buildPaginatedQuery(baseQuery, { page: 1, pageSize: 10 });
+
+// Validate SQL without applying modifications
+const isValid = builder.validateSql('SELECT id FROM users');
+console.log(isValid); // true
+```
+
+For more details, see the [DynamicQueryBuilder Usage Guide](../../docs/usage-guides/class-DynamicQueryBuilder-usage-guide.md).
 
 ---
 
@@ -352,7 +482,7 @@ const jsonQuery = builder.buildJson(baseQuery, mapping);
 // [{ "id": 1, "date": "2024-01-15", "customer": {"name": "John"}, "items": [{"product": "Widget", "qty": 2}] }]
 ```
 
-For more details, see the [PostgresJsonQueryBuilder Usage Guide](./docs/usage-guides/class-PostgresJsonQueryBuilder-usage-guide.md).
+For more details, see the [PostgresJsonQueryBuilder Usage Guide](../../docs/usage-guides/class-PostgresJsonQueryBuilder-usage-guide.md).
 
 ---
 
@@ -404,7 +534,7 @@ try {
 }
 ```
 
-For more details on `SqlSchemaValidator`, see the [SqlSchemaValidator Usage Guide](./docs/usage-guides/class-SqlSchemaValidator-usage-guide.md).
+For more details on `SqlSchemaValidator`, see the [SqlSchemaValidator Usage Guide](../../docs/usage-guides/class-SqlSchemaValidator-usage-guide.md).
 
 ---
 
@@ -440,7 +570,7 @@ console.log(updateSql);
 // 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"
 ```
 
-For more details on `QueryBuilder`, see the [QueryBuilder Usage Guide](./docs/usage-guides/class-QueryBuilder-usage-guide.md).
+For more details on `QueryBuilder`, see the [QueryBuilder Usage Guide](../../docs/usage-guides/class-QueryBuilder-usage-guide.md).
 
 ---
 
@@ -475,7 +605,7 @@ const tableColumnResolver = schemaManager.createTableColumnResolver();
 const injector = new SqlParamInjector({ tableColumnResolver });
 ```
 
-For more details on `SchemaManager`, see the [SchemaManager Usage Guide](./docs/usage-guides/class-SchemaManager-usage-guide.md).
+For more details on `SchemaManager`, see the [SchemaManager Usage Guide](../../docs/usage-guides/class-SchemaManager-usage-guide.md).
 
 ---
 

package/dist/esm/index.js

@@ -15,12 +15,16 @@ export * from './transformers/SelectValueCollector';
 export * from './transformers/SelectableColumnCollector';
 export * from './transformers/TableColumnResolver';
 export * from './transformers/TableSourceCollector';
+export * from './transformers/UnifiedJsonMapping';
 export * from './transformers/UpstreamSelectQueryFinder';
+export * from './transformers/TypeTransformationPostProcessor';
 export * from './transformers/SchemaCollector';
 export * from './transformers/SqlParamInjector';
 export * from './transformers/SqlSortInjector';
 export * from './transformers/SqlPaginationInjector';
+export * from './transformers/DynamicQueryBuilder';
 export * from './utils/SqlSchemaValidator';
+export * from './utils/JsonSchemaValidator';
 export * from './utils/SchemaManager';
 // Add more exports here if you want to expose additional public API
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAE5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AAErC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yCAAyC,CAAC;AACxD,cAAc,6BAA6B,CAAC,CAAC,0BAA0B;AACvE,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sCAAsC,CAAC;AAErD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,oEAAoE"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAE5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AAErC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yCAAyC,CAAC;AACxD,cAAc,6BAA6B,CAAC,CAAC,0BAA0B;AACvE,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC;AACpD,cAAc,mCAAmC,CAAC;AAClD,cAAc,0CAA0C,CAAC;AACzD,cAAc,gDAAgD,CAAC;AAE/D,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sCAAsC,CAAC;AACrD,cAAc,oCAAoC,CAAC;AAEnD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AACtC,oEAAoE"}