rawsql-ts 0.11.2-beta → 0.11.4-beta

package/dist/esm/types/src/index.d.ts

@@ -4,6 +4,7 @@ export * from './models/BinarySelectQuery';
 export * from './models/SelectQuery';
 export * from './models/ValueComponent';
 export * from './models/ValuesQuery';
+export * from './models/CTEError';
 export * from './transformers/CTECollector';
 export * from './transformers/CTENormalizer';
 export * from './transformers/Formatter';
@@ -32,3 +33,5 @@ export * from './transformers/DynamicQueryBuilder';
 export * from './utils/SqlSchemaValidator';
 export * from './utils/JsonSchemaValidator';
 export * from './utils/SchemaManager';
+export type { UnifiedJsonMapping, ColumnMappingConfig } from './transformers/UnifiedJsonMapping';
+export { convertUnifiedMapping } from './transformers/UnifiedJsonMapping';

package/dist/esm/types/src/models/BinarySelectQuery.d.ts

@@ -2,6 +2,7 @@ import { SourceExpression } from "./Clause";
 import type { SelectQuery } from "./SelectQuery";
 import { SqlComponent } from "./SqlComponent";
 import { RawString } from "./ValueComponent";
+import { SimpleSelectQuery } from "./SimpleSelectQuery";
 /**
  * Represents a binary SELECT query (e.g., UNION, INTERSECT, EXCEPT).
  */
@@ -94,4 +95,10 @@ export declare class BinarySelectQuery extends SqlComponent implements SelectQue
      * @param value Value to set
      */
     setParameter(name: string, value: any): this;
+    /**
+     * Converts this BinarySelectQuery to a SimpleSelectQuery using QueryBuilder.
+     * This enables CTE management on binary queries by wrapping them as subqueries.
+     * @returns A SimpleSelectQuery representation of this binary query
+     */
+    toSimpleQuery(): SimpleSelectQuery;
 }

package/dist/esm/types/src/models/CTEError.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Error thrown when a CTE with the same name already exists
+ */
+export declare class DuplicateCTEError extends Error {
+    cteName: string;
+    constructor(cteName: string);
+}
+/**
+ * Error thrown when a CTE name is invalid
+ */
+export declare class InvalidCTENameError extends Error {
+    cteName: string;
+    constructor(cteName: string, reason: string);
+}
+/**
+ * Error thrown when trying to operate on a non-existent CTE
+ */
+export declare class CTENotFoundError extends Error {
+    cteName: string;
+    constructor(cteName: string);
+}

package/dist/esm/types/src/models/Clause.d.ts

@@ -1,6 +1,7 @@
 import { SelectQuery } from "./SelectQuery";
 import { SqlComponent } from "./SqlComponent";
 import { IdentifierString, RawString, ValueComponent, WindowFrameExpression, QualifiedName } from "./ValueComponent";
+import { HintClause } from "./HintClause";
 export declare class SelectItem extends SqlComponent {
     static kind: symbol;
     value: ValueComponent;
@@ -11,7 +12,8 @@ export declare class SelectClause extends SqlComponent {
     static kind: symbol;
     items: SelectItem[];
     distinct: DistinctComponent | null;
-    constructor(items: SelectItem[], distinct?: DistinctComponent | null);
+    hints: HintClause[];
+    constructor(items: SelectItem[], distinct?: DistinctComponent | null, hints?: HintClause[]);
 }
 export type DistinctComponent = Distinct | DistinctOn;
 export declare class Distinct extends SqlComponent {

package/dist/esm/types/src/models/HintClause.d.ts

@@ -0,0 +1,24 @@
+import { SqlComponent } from "./SqlComponent";
+/**
+ * Represents a SQL hint clause
+ */
+export declare class HintClause extends SqlComponent {
+    static kind: symbol;
+    /**
+     * The hint content without the delimiters
+     */
+    hintContent: string;
+    constructor(hintContent: string);
+    /**
+     * Returns the full hint clause with delimiters
+     */
+    getFullHint(): string;
+    /**
+     * Checks if a string is a hint clause
+     */
+    static isHintClause(value: string): boolean;
+    /**
+     * Extracts hint content from a hint clause string
+     */
+    static extractHintContent(hintClause: string): string;
+}

package/dist/esm/types/src/models/SelectQuery.d.ts

@@ -3,7 +3,19 @@ import { InsertQuery } from "./InsertQuery";
 import { SimpleSelectQuery } from "./SimpleSelectQuery";
 import { BinarySelectQuery } from "./BinarySelectQuery";
 import { ValuesQuery } from "./ValuesQuery";
+export interface CTEOptions {
+    materialized?: boolean | null;
+}
+export { DuplicateCTEError, InvalidCTENameError, CTENotFoundError } from './CTEError';
+export interface CTEManagement {
+    addCTE(name: string, query: SelectQuery, options?: CTEOptions): this;
+    removeCTE(name: string): this;
+    hasCTE(name: string): boolean;
+    getCTENames(): string[];
+    replaceCTE(name: string, query: SelectQuery, options?: CTEOptions): this;
+}
 export interface SelectQuery extends SqlComponent {
     setParameter(name: string, value: any): this;
+    toSimpleQuery(): SimpleSelectQuery;
 }
 export { SimpleSelectQuery, BinarySelectQuery, ValuesQuery, InsertQuery };

package/dist/esm/types/src/models/SimpleSelectQuery.d.ts

@@ -2,12 +2,12 @@ import { SqlComponent } from "./SqlComponent";
 import { ForClause, FromClause, GroupByClause, HavingClause, LimitClause, OrderByClause, SelectClause, SourceExpression, WhereClause, WindowsClause as WindowClause, WithClause, CommonTable, OffsetClause, FetchClause } from "./Clause";
 import { ValueComponent } from "./ValueComponent";
 import { BinarySelectQuery } from "./BinarySelectQuery";
-import type { SelectQuery } from "./SelectQuery";
+import type { SelectQuery, CTEOptions, CTEManagement } from "./SelectQuery";
 import { TableColumnResolver } from "../transformers/TableColumnResolver";
 /**
  * Represents a simple SELECT query in SQL.
  */
-export declare class SimpleSelectQuery extends SqlComponent implements SelectQuery {
+export declare class SimpleSelectQuery extends SqlComponent implements SelectQuery, CTEManagement {
     static kind: symbol;
     withClause: WithClause | null;
     selectClause: SelectClause;
@@ -21,6 +21,7 @@ export declare class SimpleSelectQuery extends SqlComponent implements SelectQue
     offsetClause: OffsetClause | null;
     fetchClause: FetchClause | null;
     forClause: ForClause | null;
+    private cteNameCache;
     constructor(params: {
         selectClause: SelectClause;
         fromClause?: FromClause | null;
@@ -35,6 +36,12 @@ export declare class SimpleSelectQuery extends SqlComponent implements SelectQue
         forClause?: ForClause | null;
         withClause?: WithClause | null;
     });
+    /**
+     * Initializes the CTE name cache from existing withClause.
+     * Called during construction and when withClause is modified externally.
+     * @private
+     */
+    private initializeCTECache;
     /**
      * Creates a new BinarySelectQuery with this query as the left side and the provided query as the right side,
      * using UNION as the operator.
@@ -216,4 +223,161 @@ export declare class SimpleSelectQuery extends SqlComponent implements SelectQue
      * @param value Value to set
      */
     setParameter(name: string, value: any): this;
+    /**
+     * Returns this SimpleSelectQuery instance (identity function).
+     * @returns This SimpleSelectQuery instance
+     */
+    toSimpleQuery(): SimpleSelectQuery;
+    /**
+     * Adds a CTE (Common Table Expression) to the query.
+     *
+     * @param name CTE name/alias (must be non-empty)
+     * @param query SelectQuery to use as CTE
+     * @param options Optional configuration
+     * @param options.materialized PostgreSQL-specific: true = MATERIALIZED, false = NOT MATERIALIZED, null/undefined = no hint
+     *
+     * @throws {InvalidCTENameError} When name is empty or whitespace-only
+     * @throws {DuplicateCTEError} When CTE with same name already exists
+     *
+     * @example
+     * ```typescript
+     * // Basic CTE
+     * query.addCTE('active_users',
+     *   SelectQueryParser.parse('SELECT * FROM users WHERE active = true')
+     * );
+     *
+     * // PostgreSQL MATERIALIZED CTE (forces materialization)
+     * query.addCTE('expensive_calc', expensiveQuery, { materialized: true });
+     *
+     * // PostgreSQL NOT MATERIALIZED CTE (prevents materialization)
+     * query.addCTE('simple_view', simpleQuery, { materialized: false });
+     * ```
+     *
+     * @remarks
+     * - MATERIALIZED/NOT MATERIALIZED is PostgreSQL-specific syntax
+     * - Other databases will ignore the materialized hint
+     * - CTE names must be unique within the query
+     * - Method supports fluent chaining
+     */
+    addCTE(name: string, query: SelectQuery, options?: CTEOptions): this;
+    /**
+     * Removes a CTE by name from the query.
+     *
+     * @param name CTE name to remove
+     *
+     * @throws {CTENotFoundError} When CTE with specified name doesn't exist
+     *
+     * @example
+     * ```typescript
+     * query.addCTE('temp_data', tempQuery);
+     * query.removeCTE('temp_data'); // Removes the CTE
+     *
+     * // Throws CTENotFoundError
+     * query.removeCTE('non_existent');
+     * ```
+     *
+     * @remarks
+     * - Throws error if CTE doesn't exist (strict mode for safety)
+     * - Use hasCTE() to check existence before removal if needed
+     * - Method supports fluent chaining
+     */
+    removeCTE(name: string): this;
+    /**
+     * Checks if a CTE with the given name exists in the query.
+     * Optimized with O(1) lookup using internal cache.
+     *
+     * @param name CTE name to check
+     * @returns true if CTE exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * query.addCTE('user_stats', statsQuery);
+     *
+     * if (query.hasCTE('user_stats')) {
+     *   console.log('CTE exists');
+     * }
+     *
+     * query.removeCTE('user_stats');
+     * console.log(query.hasCTE('user_stats')); // false
+     * ```
+     *
+     * @remarks
+     * - Performs case-sensitive name matching
+     * - Returns false for queries without any CTEs
+     * - Useful for conditional CTE operations
+     * - O(1) performance using internal cache
+     */
+    hasCTE(name: string): boolean;
+    /**
+     * Returns an array of all CTE names in the query.
+     *
+     * @returns Array of CTE names in the order they were defined
+     *
+     * @example
+     * ```typescript
+     * const query = SelectQueryParser.parse('SELECT * FROM data').toSimpleQuery();
+     *
+     * // Empty query
+     * console.log(query.getCTENames()); // []
+     *
+     * // Add CTEs
+     * query.addCTE('users', userQuery);
+     * query.addCTE('orders', orderQuery);
+     *
+     * console.log(query.getCTENames()); // ['users', 'orders']
+     *
+     * // Use for validation
+     * const expectedCTEs = ['users', 'orders', 'products'];
+     * const actualCTEs = query.getCTENames();
+     * const missingCTEs = expectedCTEs.filter(name => !actualCTEs.includes(name));
+     * ```
+     *
+     * @remarks
+     * - Returns empty array for queries without CTEs
+     * - Names are returned in definition order
+     * - Useful for debugging and validation
+     * - Names reflect actual CTE aliases, not table references
+     * - Performance: O(n) but avoids redundant array mapping
+     */
+    getCTENames(): string[];
+    /**
+     * Replaces an existing CTE or adds a new one with the given name.
+     *
+     * @param name CTE name to replace/add (must be non-empty)
+     * @param query SelectQuery to use as CTE
+     * @param options Optional configuration
+     * @param options.materialized PostgreSQL-specific: true = MATERIALIZED, false = NOT MATERIALIZED, null/undefined = no hint
+     *
+     * @throws {InvalidCTENameError} When name is empty or whitespace-only
+     *
+     * @example
+     * ```typescript
+     * const query = SelectQueryParser.parse('SELECT * FROM final_data').toSimpleQuery();
+     * const oldQuery = SelectQueryParser.parse('SELECT id FROM old_table');
+     * const newQuery = SelectQueryParser.parse('SELECT id, status FROM new_table WHERE active = true');
+     *
+     * // Add initial CTE
+     * query.addCTE('data_source', oldQuery);
+     *
+     * // Replace with improved version
+     * query.replaceCTE('data_source', newQuery, { materialized: true });
+     *
+     * // Safe replacement - adds if doesn't exist
+     * query.replaceCTE('new_cte', newQuery); // Won't throw error
+     *
+     * // Chaining replacements
+     * query
+     *   .replaceCTE('cte1', query1, { materialized: false })
+     *   .replaceCTE('cte2', query2, { materialized: true });
+     * ```
+     *
+     * @remarks
+     * - Unlike addCTE(), this method won't throw error if CTE already exists
+     * - Unlike removeCTE(), this method won't throw error if CTE doesn't exist
+     * - Useful for upsert-style CTE operations
+     * - MATERIALIZED/NOT MATERIALIZED is PostgreSQL-specific
+     * - Method supports fluent chaining
+     * - Maintains CTE order when replacing existing CTEs
+     */
+    replaceCTE(name: string, query: SelectQuery, options?: CTEOptions): this;
 }

package/dist/esm/types/src/models/ValuesQuery.d.ts

@@ -15,7 +15,7 @@ export declare class ValuesQuery extends SqlComponent implements SelectQuery {
      */
     columnAliases: string[] | null;
     constructor(tuples: TupleExpression[], columnAliases?: string[] | null);
-    toSimpleSelectQuery(): SimpleSelectQuery;
+    toSimpleQuery(): SimpleSelectQuery;
     /**
        * Sets the value of a parameter by name in this query.
        * @param name Parameter name

package/dist/esm/types/src/parsers/SqlPrintTokenParser.d.ts

@@ -73,6 +73,10 @@ export declare class SqlPrintTokenParser implements SqlComponentVisitor<SqlPrint
         params: any[] | Record<string, any>[] | Record<string, any>;
     };
     visit(arg: SqlComponent): SqlPrintToken;
+    /**
+     * Adds comment tokens to a SqlPrintToken based on the comments array
+     */
+    private addCommentsToToken;
     private visitValueList;
     private visitColumnReference;
     private visitFunctionCall;
@@ -108,6 +112,7 @@ export declare class SqlPrintTokenParser implements SqlComponentVisitor<SqlPrint
     private visitWindowFrameBoundStatic;
     private visitSelectItem;
     private visitSelectClause;
+    private visitHintClause;
     private visitDistinct;
     private visitDistinctOn;
     private visitTableSource;

package/dist/esm/types/src/transformers/SqlFormatter.d.ts

@@ -26,6 +26,8 @@ export declare class SqlFormatter {
         keywordCase?: 'none' | 'upper' | 'lower';
         commaBreak?: CommaBreakStyle;
         andBreak?: AndBreakStyle;
+        exportComment?: boolean;
+        strictCommentPlacement?: boolean;
     }); /**
      * Formats a SQL query string with the given parameters.
      * @param sqlText The SQL query string to format.

package/dist/esm/types/src/transformers/SqlParameterBinder.d.ts

@@ -0,0 +1,36 @@
+import { SelectQuery, SimpleSelectQuery } from "../models/SelectQuery";
+/**
+ * Options for SqlParameterBinder
+ */
+export interface SqlParameterBinderOptions {
+    /** Whether to throw an error if a parameter value is missing (defaults to true) */
+    requireAllParameters?: boolean;
+}
+/**
+ * SqlParameterBinder binds values to existing hardcoded parameters in SQL queries.
+ *
+ * This transformer is designed to work with SQL queries that already contain
+ * parameter placeholders (e.g., :param_name) and bind actual values to them.
+ *
+ * Unlike SqlParamInjector which creates new WHERE conditions, this transformer
+ * only sets values for parameters that already exist in the parsed SQL.
+ */
+export declare class SqlParameterBinder {
+    private options;
+    constructor(options?: SqlParameterBinderOptions);
+    /**
+     * Binds values to existing hardcoded parameters in the query.
+     * @param query The SelectQuery to modify
+     * @param parameterValues A record of parameter names and values to bind
+     * @returns The modified SelectQuery with parameter values set
+     * @throws Error when required parameters are missing values
+     */
+    bind(query: SelectQuery, parameterValues: Record<string, any>): SelectQuery;
+    /**
+     * Convenience method to bind parameters to a SimpleSelectQuery.
+     * @param query The SimpleSelectQuery to modify
+     * @param parameterValues A record of parameter names and values to bind
+     * @returns The modified SelectQuery with parameter values set
+     */
+    bindToSimpleQuery(query: SimpleSelectQuery, parameterValues: Record<string, any>): SelectQuery;
+}

package/dist/esm/types/src/transformers/SqlPrinter.d.ts

@@ -30,6 +30,10 @@ export declare class SqlPrinter {
     andBreak: AndBreakStyle;
     /** Keyword case style: 'none', 'upper' | 'lower' */
     keywordCase: 'none' | 'upper' | 'lower';
+    /** Whether to export comments in the output (default: false for compatibility) */
+    exportComment: boolean;
+    /** Whether to use strict comment placement (only clause-level comments, default: false) */
+    strictCommentPlacement: boolean;
     private linePrinter;
     private indentIncrementContainers;
     /**
@@ -42,6 +46,8 @@ export declare class SqlPrinter {
         commaBreak?: CommaBreakStyle;
         andBreak?: AndBreakStyle;
         keywordCase?: 'none' | 'upper' | 'lower';
+        exportComment?: boolean;
+        strictCommentPlacement?: boolean;
         indentIncrementContainerTypes?: string[];
     });
     /**

package/dist/esm/types/src/utils/CommentUtils.d.ts

@@ -0,0 +1,21 @@
+import { Lexeme } from "../models/Lexeme";
+/**
+ * Utility functions for handling comments in parsers
+ */
+export declare class CommentUtils {
+    /**
+     * Collects comments from preceding tokens that are associated with a specific keyword.
+     * This function looks for comments in tokens before the current position that might
+     * be related to the current clause.
+     *
+     * @param lexemes Array of lexemes
+     * @param currentIndex Index of the current keyword token
+     * @param keywordValue Expected keyword value (e.g., 'from', 'where')
+     * @returns Array of comments associated with this clause
+     */
+    static collectClauseComments(lexemes: Lexeme[], currentIndex: number, keywordValue: string): string[] | null;
+    /**
+     * Checks if a token value is a significant SQL keyword that would separate clauses
+     */
+    private static isSignificantSqlKeyword;
+}

package/dist/esm/types/src/utils/ParameterDetector.d.ts

@@ -0,0 +1,32 @@
+import { SqlComponent } from "../models/SqlComponent";
+/**
+ * Utility class for detecting hardcoded parameters in SQL queries.
+ *
+ * This class helps identify existing ParameterExpression nodes in parsed SQL,
+ * which represent hardcoded parameters like :param_name in the original SQL.
+ */
+export declare class ParameterDetector {
+    /**
+     * Extracts all hardcoded parameter names from a parsed SQL query.
+     * @param query The parsed SQL query (must be a SqlComponent)
+     * @returns Array of parameter names found in the query
+     */
+    static extractParameterNames(query: SqlComponent): string[];
+    /**
+     * Checks if a parameter with the given name exists in the query.
+     * @param query The parsed SQL query (must be a SqlComponent)
+     * @param parameterName The parameter name to check
+     * @returns True if the parameter exists, false otherwise
+     */
+    static hasParameter(query: SqlComponent, parameterName: string): boolean;
+    /**
+     * Separates filter options into hardcoded parameters and dynamic column filters.
+     * @param query The parsed SQL query (must be a SqlComponent)
+     * @param filter The filter object from DynamicQueryBuilder options
+     * @returns Object with separated hardcoded and dynamic filters
+     */
+    static separateFilters(query: SqlComponent, filter: Record<string, any>): {
+        hardcodedParams: Record<string, any>;
+        dynamicFilters: Record<string, any>;
+    };
+}