rawsql-ts 0.10.3-beta → 0.10.5-beta

package/README.md

@@ -23,7 +23,9 @@ 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
-- Dynamic SQL parameter injection for building flexible search queries with `SqlParamInjector`
+- 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
 - Type-safe schema management and JSON mapping conversion with full TypeScript support
 - Static query validation and regression testing against your database schema with `SqlSchemaValidator`, enabling early error detection and robust unit tests for schema changes.
 
@@ -64,43 +66,46 @@ npm install rawsql-ts
 
 ## Quick Start
 
----
-
 Kickstart your project by dynamically injecting parameters with `SqlParamInjector` for flexible query generation right from the start!
 
 ```typescript
 import { SqlParamInjector, SqlFormatter } from 'rawsql-ts';
 
-// 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`;
+// 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`;
 
-// Imagine you have search parameters from a user's input
+// Search parameters with OR conditions and AND combination
 const searchParams = {
-  user_name: { like: '%Alice%' }, // Find users whose name contains 'Alice'
-  email: 'specific.email@example.com' // And have a specific email
+  name_or_email: {
+    or: [
+      { column: 'user_name', ilike: '%alice%' },
+      { column: 'email', ilike: '%alice%' }
+    ]
+  },
+  phone: { like: '%080%' }  // AND condition
 };
 
 const injector = new SqlParamInjector();
 // Dynamically inject searchParams into the baseSql
 const query = injector.inject(baseSql, searchParams);
 
-// Format the dynamically generated query (e.g., using PostgreSQL preset)
+// Format the dynamically generated query
 const formatter = new SqlFormatter({ preset: 'postgres' }); 
 const { formattedSql, params } = formatter.format(query);
 
-console.log('Dynamically Generated SQL:');
+console.log('Generated SQL:');
 console.log(formattedSql);
-// Expected output (PostgreSQL style):
-// select "u"."user_id", "u"."user_name", "u"."email"
+// Output:
+// select "u"."user_id", "u"."user_name", "u"."email", "u"."phone"
 // from "users" as "u"
 // where "u"."active" = true
-// and "u"."user_name" like :user_name_like
-// and "u"."email" = :email
+//   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
 
-console.log('\\nParameters:');
+console.log('Parameters:');
 console.log(params);
-// Expected output:
-// { user_name_like: '%Alice%', email: 'specific.email@example.com' }
+// Output: { name_or_email_or_0_ilike: '%alice%', name_or_email_or_1_ilike: '%alice%', phone_like: '%080%' }
 ```
 
 ---
@@ -177,6 +182,8 @@ Key benefits include:
 - **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.
+- **Rich Operator Support**: Supports various SQL operators including equality, comparison, range (min/max), pattern matching (like/ilike), IN clauses, and PostgreSQL array operators.
+- **Advanced Condition Logic**: Supports OR/AND conditions, automatic parentheses grouping, and explicit column mapping for flexible query construction.
 
 ```typescript
 import { SqlParamInjector, SqlFormatter } from 'rawsql-ts';
@@ -199,6 +206,109 @@ For more details, see the [SqlParamInjector Usage Guide](./docs/usage-guides/cla
 
 ---
 
+## SqlSortInjector Features
+
+The `SqlSortInjector` class enables dynamic ORDER BY clause injection into SQL queries, providing a clean and flexible way to handle sorting requirements. Instead of manually constructing different SQL statements for various sorting scenarios, you can inject sort conditions into your base SQL query, making your code more maintainable and reusable.
+
+Key benefits include:
+- **Dynamic Sort Injection**: Add ORDER BY conditions to existing queries without modifying the base SQL
+- **Flexible Sort Options**: Support for ASC/DESC directions with NULLS FIRST/LAST positioning
+- **Append Mode**: Preserves existing ORDER BY clauses and appends new conditions
+- **Column Alias Support**: Works seamlessly with column aliases and calculated expressions
+- **TableColumnResolver Integration**: Supports wildcard SELECT queries through schema resolution
+- **Clean Separation**: Remove existing ORDER BY clauses when needed with `removeOrderBy()`
+
+```typescript
+import { SqlSortInjector, SqlFormatter } from 'rawsql-ts';
+
+// Basic sort injection
+const baseSql = 'SELECT id, name, created_at FROM users WHERE active = true';
+const sortConditions = {
+  created_at: { desc: true, nullsLast: true },
+  name: { asc: true }
+};
+
+const injector = new SqlSortInjector();
+const sortedQuery = injector.inject(baseSql, sortConditions);
+
+const formatter = new SqlFormatter();
+const { formattedSql } = formatter.format(sortedQuery);
+
+console.log(formattedSql);
+// Output: select "id", "name", "created_at" from "users" where "active" = true order by "created_at" desc nulls last, "name"
+
+// Append to existing ORDER BY
+const existingSql = 'SELECT id, name FROM users ORDER BY id ASC';
+const additionalSort = { name: { desc: true } };
+const appendedQuery = injector.inject(existingSql, additionalSort);
+// Result: SELECT id, name FROM users ORDER BY id ASC, name DESC
+
+// Remove existing ORDER BY when needed
+const cleanQuery = SqlSortInjector.removeOrderBy(existingSql);
+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).
+
+---
+
+## SqlPaginationInjector Features
+
+The `SqlPaginationInjector` class enables dynamic LIMIT/OFFSET clause injection into SQL queries, providing a clean and efficient way to handle data pagination. Instead of manually constructing different SQL statements for various page sizes and offsets, you can inject pagination into your base SQL query, making your code more maintainable and performance-optimized.
+
+Key benefits include:
+- **Page-Based Pagination**: Simple page number and page size configuration with automatic offset calculation
+- **Automatic OFFSET Optimization**: Smart handling where page 1 omits unnecessary OFFSET 0 clauses
+- **Existing Clause Detection**: Prevents conflicts by detecting and reporting existing LIMIT/OFFSET clauses
+- **Validation & Safety**: Built-in validation for page numbers, page sizes, and configurable maximum limits
+- **Clean Removal**: Remove existing pagination clauses when needed with `removePagination()`
+- **Performance Conscious**: Generates standard LIMIT/OFFSET patterns optimized for database engines
+
+```typescript
+import { SqlPaginationInjector, SqlFormatter } from 'rawsql-ts';
+
+// Basic pagination injection
+const baseSql = 'SELECT id, name, email FROM users WHERE active = true ORDER BY created_at DESC';
+const pagination = {
+  page: 2,        // Page number (1-based)
+  pageSize: 20    // Items per page
+};
+
+const injector = new SqlPaginationInjector();
+const paginatedQuery = injector.inject(baseSql, pagination);
+
+const formatter = new SqlFormatter();
+const { formattedSql } = formatter.format(paginatedQuery);
+
+console.log(formattedSql);
+// Output: select "id", "name", "email" from "users" where "active" = true order by "created_at" desc limit 20 offset 20
+
+// First page optimization (no OFFSET needed)
+const firstPagePagination = { page: 1, pageSize: 10 };
+const firstPageQuery = injector.inject(baseSql, firstPagePagination);
+const { formattedSql: firstPageSql } = formatter.format(firstPageQuery);
+console.log(firstPageSql);
+// Output: select "id", "name", "email" from "users" where "active" = true order by "created_at" desc limit 10
+
+// Remove existing pagination when needed
+const existingPaginatedSql = 'SELECT id, name FROM users LIMIT 50 OFFSET 100';
+const cleanQuery = SqlPaginationInjector.removePagination(existingPaginatedSql);
+const newPagination = { page: 1, pageSize: 25 };
+const repaginatedQuery = injector.inject(cleanQuery, newPagination);
+// Result: Clean query with new pagination applied
+
+// Combine with other injectors for complete query building
+let query = new SqlParamInjector().inject(baseSql, { status: 'active' });
+query = new SqlSortInjector().inject(query, { created_at: { desc: true } });
+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).
+
+---
+
 ## PostgresJsonQueryBuilder Features
 
 The `PostgresJsonQueryBuilder` 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.

package/dist/esm/index.js

@@ -18,6 +18,8 @@ export * from './transformers/TableSourceCollector';
 export * from './transformers/UpstreamSelectQueryFinder';
 export * from './transformers/SchemaCollector';
 export * from './transformers/SqlParamInjector';
+export * from './transformers/SqlSortInjector';
+export * from './transformers/SqlPaginationInjector';
 export * from './utils/SqlSchemaValidator';
 export * from './utils/SchemaManager';
 // Add more exports here if you want to expose additional public API

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;AAEhD,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,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"}