rawsql-ts 0.11.7-beta → 0.11.9-beta

package/README.md

@@ -246,7 +246,7 @@ For SelectQueryParser details, see the [SelectQueryParser Usage Guide](../../doc
 
 ## SqlFormatter Features
 
-The `SqlFormatter` class is the recommended way to format SQL queries, offering advanced capabilities like indentation, keyword casing, and multi-line formatting.
+The `SqlFormatter` class is the recommended way to format SQL queries, offering advanced capabilities like indentation, keyword casing, multi-line formatting, and comprehensive comment preservation.
 It also allows for detailed style customization. For example, you can define your own formatting rules:
 
 ```typescript
@@ -286,6 +286,43 @@ order by
 */
 ```
 
+### Comment Handling
+
+SqlFormatter provides comprehensive comment parsing and export capabilities:
+
+```typescript
+import { SqlFormatter } from 'rawsql-ts';
+
+// Enable comment export (disabled by default for backward compatibility)
+const formatter = new SqlFormatter({ 
+  exportComment: true,
+  strictCommentPlacement: true  // Only export comments from clause-level keywords
+});
+
+const sqlWithComments = `
+  -- This is a query to get active users
+  SELECT 
+    u.id, 
+    u.name /* User's full name */
+  FROM users u
+  WHERE u.active = true -- Only active users
+`;
+
+const query = SelectQueryParser.parse(sqlWithComments);
+const { formattedSql } = formatter.format(query);
+
+console.log(formattedSql);
+// Output includes comments preserved as block comments for SQL safety
+```
+
+**Comment Features:**
+- **Full Comment Parsing**: Supports both `--` line comments and `/* */` block comments
+- **AST Preservation**: Comments are stored in the Abstract Syntax Tree and preserved throughout transformations
+- **Safe Export**: Line comments are automatically converted to block comments during export to prevent SQL structure issues
+- **Configurable Export**: Enable/disable comment export with `exportComment` option
+- **Comment Editing API**: Programmatically add, edit, delete, and search comments using the `CommentEditor` class
+- **Clause Association**: Comments can be associated with specific SQL clauses and keywords
+
 For more details, see the [SqlFormatter Usage Guide](../../docs/usage-guides/class-SqlFormatter-usage-guide.md).
 
 ---
@@ -492,6 +529,50 @@ For more details, see the [DynamicQueryBuilder Usage Guide](../../docs/usage-gui
 
 ---
 
+## Query Flow Diagram Generation
+
+Generate Mermaid flow diagrams from SQL queries to visualize data flow and query execution order.
+
+```typescript
+import { QueryFlowDiagramGenerator } from 'rawsql-ts';
+
+const sql = `
+  WITH user_stats AS (
+    SELECT user_id, COUNT(*) as post_count
+    FROM posts GROUP BY user_id
+  )
+  SELECT u.name, us.post_count
+  FROM users u
+  LEFT JOIN user_stats us ON u.id = us.user_id
+`;
+
+const mermaid = QueryFlowDiagramGenerator.generate(sql);
+console.log(mermaid);
+// Output: Mermaid flowchart showing data flow through SQL operations
+```
+
+### Symbol Reference
+
+| SQL Element | Shape | Example |
+|-------------|-------|---------|
+| Table/CTE/Subquery | Cylinder | `table_users[(users)]`, `cte_stats[(CTE:user_stats)]` |
+| SELECT/WHERE/GROUP BY | Hexagon | `{{SELECT}}`, `{{WHERE}}` |
+| JOIN/UNION | Diamond | `{LEFT JOIN}`, `{UNION ALL}` |
+
+Example output for CTE query:
+```mermaid
+flowchart TD
+    table_posts[(posts)] --> cte_user_stats_group_by{{GROUP BY}}
+    cte_user_stats_group_by --> cte_user_stats_select{{SELECT}}
+    cte_user_stats_select --> cte_user_stats[(CTE:user_stats)]
+    table_users[(users)] -->|NOT NULL| join_1{LEFT JOIN}
+    cte_user_stats -->|NULLABLE| join_1
+    join_1 --> main_select{{SELECT}}
+    main_select --> main_output(Final Result)
+```
+
+---
+
 ## 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

@@ -27,6 +27,7 @@ export { unifyJsonMapping } from './transformers/JsonMappingUnifier';
 export * from './transformers/UpstreamSelectQueryFinder';
 export * from './transformers/TypeTransformationPostProcessor';
 export * from './transformers/SchemaCollector';
+export * from './transformers/QueryFlowDiagramGenerator';
 export * from './transformers/SqlParamInjector';
 export * from './transformers/SqlSortInjector';
 export * from './transformers/SqlPaginationInjector';

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;AACrC,cAAc,mBAAmB,CAAC;AAElC,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,qCAAqC,CAAC;AACpD,cAAc,oCAAoC,CAAC;AACnD,OAAO,EAEH,yBAAyB,EACzB,0BAA0B,EAK7B,MAAM,uCAAuC,CAAC;AAC/C,OAAO;AACH,6DAA6D;AAC7D,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,cAAc,EACjB,MAAM,mCAAmC,CAAC;AAE3C,qEAAqE;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,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,cAAc,uBAAuB,CAAC;AAGtC,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;AACrC,cAAc,mBAAmB,CAAC;AAElC,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,qCAAqC,CAAC;AACpD,cAAc,oCAAoC,CAAC;AACnD,OAAO,EAEH,yBAAyB,EACzB,0BAA0B,EAK7B,MAAM,uCAAuC,CAAC;AAC/C,OAAO;AACH,6DAA6D;AAC7D,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,cAAc,EACjB,MAAM,mCAAmC,CAAC;AAE3C,qEAAqE;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,cAAc,0CAA0C,CAAC;AACzD,cAAc,gDAAgD,CAAC;AAE/D,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0CAA0C,CAAC;AACzD,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,cAAc,uBAAuB,CAAC;AAGtC,oEAAoE"}