rawsql-ts 0.10.4-beta → 0.10.6-beta

package/README.md

@@ -24,6 +24,8 @@ It is designed for extensibility and advanced SQL analysis, with initial focus o
 - 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` (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.
 
@@ -204,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.