rawsql-ts 0.10.9-beta → 0.11.1-beta

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

@@ -14,10 +14,16 @@ export * from './transformers/SelectValueCollector';
 export * from './transformers/SelectableColumnCollector';
 export * from './transformers/TableColumnResolver';
 export * from './transformers/TableSourceCollector';
+export * from './transformers/UnifiedJsonMapping';
+export { ModelDrivenJsonMapping, convertModelDrivenMapping, validateModelDrivenMapping, FieldMapping, NestedStructure, StructureFields, FieldType } from './transformers/ModelDrivenJsonMapping';
+export { processJsonMapping, unifyJsonMapping, isModelDrivenFormat, isUnifiedFormat, isLegacyFormat } from './transformers/JsonMappingUnifier';
 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';

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

@@ -0,0 +1,58 @@
+import { SelectQuery } from "../models/SelectQuery";
+/**
+ * CTE dependency tree node for visualization
+ */
+export interface CTENode {
+    name: string;
+    columns: string[];
+    dependencies: string[];
+    dependents: string[];
+    query: SelectQuery;
+    level: number;
+}
+/**
+ * CTE dependency graph for debugging complex queries
+ */
+export interface CTEGraph {
+    nodes: Map<string, CTENode>;
+    rootNodes: string[];
+    leafNodes: string[];
+}
+/**
+ * Debug utility for visualizing CTE dependencies and column search paths
+ */
+export declare class CTEDependencyTracer {
+    private columnCollector;
+    private silent;
+    constructor(options?: {
+        silent?: boolean;
+    });
+    /**
+     * Build complete CTE dependency graph
+     */
+    buildGraph(query: SelectQuery): CTEGraph;
+    /**
+     * Trace column search path through CTE dependencies
+     */
+    traceColumnSearch(query: SelectQuery, columnName: string): {
+        searchPath: string[];
+        foundIn: string[];
+        notFoundIn: string[];
+        graph: CTEGraph;
+    };
+    /**
+     * Print visual representation of CTE dependency graph
+     */
+    printGraph(graph: CTEGraph): void;
+    /**
+     * Print column search trace
+     */
+    printColumnTrace(columnName: string, trace: ReturnType<typeof this.traceColumnSearch>): void;
+    /**
+     * Find CTEs that are actually referenced in the given query.
+     * Uses TableSourceCollector to properly identify table references from the AST.
+     */
+    private findReferencedCTEs;
+    private calculateLevels;
+    private getSearchOrder;
+}

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

@@ -0,0 +1,108 @@
+import { SelectQuery } from "../models/SelectQuery";
+import { SortConditions } from "./SqlSortInjector";
+import { PaginationOptions } from "./SqlPaginationInjector";
+import { JsonMapping } from "./PostgresJsonQueryBuilder";
+/**
+ * Options for dynamic query building
+ */
+export interface QueryBuildOptions {
+    /** Filter conditions to inject into WHERE clause */
+    filter?: Record<string, any>;
+    /** Sort conditions to inject into ORDER BY clause */
+    sort?: SortConditions;
+    /** Pagination options to inject LIMIT/OFFSET clauses */
+    paging?: PaginationOptions;
+    /** JSON serialization mapping to transform results into hierarchical JSON
+     * - JsonMapping object: explicit mapping configuration
+     * - true: auto-load mapping from corresponding .json file
+     * - false/undefined: no serialization
+     */
+    serialize?: JsonMapping | boolean;
+}
+/**
+ * DynamicQueryBuilder provides pure JavaScript SQL query building capabilities.
+ * It combines SQL parsing with dynamic condition injection (filtering, sorting, pagination, serialization).
+ *
+ * This class is framework-agnostic and does not perform any file I/O operations.
+ * It only works with SQL content provided as strings.
+ *
+ * Key features:
+ * - Pure JavaScript/TypeScript - no file system dependencies
+ * - Framework-agnostic - can be used with any database framework
+ * - Composable - combines multiple injectors in the correct order
+ * - Type-safe - provides TypeScript types for all options
+ * - Testable - easy to unit test without mocking file system
+ */
+export declare class DynamicQueryBuilder {
+    private tableColumnResolver?;
+    /**
+     * Creates a new DynamicQueryBuilder instance
+     * @param tableColumnResolver Optional function to resolve table columns for wildcard queries
+     */
+    constructor(tableColumnResolver?: (tableName: string) => string[]);
+    /**
+     * Builds a SelectQuery from SQL content with dynamic conditions.
+     * This is a pure function that does not perform any I/O operations.
+     *     * @param sqlContent Raw SQL string to parse and modify
+     * @param options Dynamic conditions to apply (filter, sort, paging, serialize)
+     * @returns Modified SelectQuery with all dynamic conditions applied
+     *     * @example
+     * ```typescript
+     * const builder = new DynamicQueryBuilder();
+     * const query = builder.buildQuery(
+     *   'SELECT id, name FROM users WHERE active = true',
+     *   {
+     *     filter: { status: 'premium' },
+     *     sort: { created_at: { desc: true } },
+     *     paging: { page: 2, pageSize: 10 },
+     *     serialize: { rootName: 'user', rootEntity: { id: 'user', name: 'User', columns: { id: 'id', name: 'name' } }, nestedEntities: [] }
+     *   }
+     * );
+     * ```
+     */
+    buildQuery(sqlContent: string, options?: QueryBuildOptions): SelectQuery;
+    /**
+     * Builds a SelectQuery with only filtering applied.
+     * Convenience method for when you only need dynamic WHERE conditions.
+     *
+     * @param sqlContent Raw SQL string to parse and modify
+     * @param filter Filter conditions to apply
+     * @returns Modified SelectQuery with filter conditions applied
+     */
+    buildFilteredQuery(sqlContent: string, filter: Record<string, any>): SelectQuery;
+    /**
+     * Builds a SelectQuery with only sorting applied.
+     * Convenience method for when you only need dynamic ORDER BY clauses.
+     *
+     * @param sqlContent Raw SQL string to parse and modify
+     * @param sort Sort conditions to apply
+     * @returns Modified SelectQuery with sort conditions applied
+     */
+    buildSortedQuery(sqlContent: string, sort: SortConditions): SelectQuery; /**
+     * Builds a SelectQuery with only pagination applied.
+     * Convenience method for when you only need LIMIT/OFFSET clauses.
+     *
+     * @param sqlContent Raw SQL string to parse and modify
+     * @param paging Pagination options to apply
+     * @returns Modified SelectQuery with pagination applied
+     */
+    buildPaginatedQuery(sqlContent: string, paging: PaginationOptions): SelectQuery;
+    /**
+     * Builds a SelectQuery with only JSON serialization applied.
+     * Convenience method for when you only need hierarchical JSON transformation.
+     *
+     * @param sqlContent Raw SQL string to parse and modify
+     * @param serialize JSON mapping configuration to apply
+     * @returns Modified SelectQuery with JSON serialization applied
+     */
+    buildSerializedQuery(sqlContent: string, serialize: JsonMapping): SelectQuery;
+    /**
+     * Validates SQL content by attempting to parse it.
+     * Useful for testing SQL validity without applying any modifications.
+     *
+     * @param sqlContent Raw SQL string to validate
+     * @returns true if SQL is valid, throws error if invalid
+     * @throws Error if SQL cannot be parsed
+     */
+    validateSql(sqlContent: string): boolean;
+}

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

@@ -0,0 +1,95 @@
+/**
+ * Unified JSON Mapping processor that supports both legacy and model-driven formats.
+ *
+ * This module provides backward compatibility while encouraging migration to the model-driven format.
+ * It automatically detects the input format and normalizes to a consistent internal representation.
+ */
+import { JsonMapping } from './PostgresJsonQueryBuilder';
+import { ModelDrivenJsonMapping } from './ModelDrivenJsonMapping';
+/**
+ * Unified mapping format that can handle both legacy and model-driven inputs.
+ */
+export interface UnifiedMappingInput {
+    typeInfo?: {
+        interface: string;
+        importPath: string;
+    };
+    structure?: any;
+    protectedStringFields?: string[];
+    rootName?: string;
+    rootEntity?: any;
+    nestedEntities?: any[];
+    columns?: any;
+    relationships?: any;
+}
+/**
+ * Result of mapping format detection and conversion.
+ */
+export interface MappingProcessResult {
+    format: 'model-driven' | 'unified' | 'legacy';
+    jsonMapping: JsonMapping;
+    originalInput: UnifiedMappingInput;
+    metadata?: {
+        typeInfo?: {
+            interface: string;
+            importPath: string;
+        };
+        protectedStringFields?: string[];
+        typeProtection?: any;
+    };
+}
+/**
+ * Detects the format of a JSON mapping configuration.
+ *
+ * @param input - The mapping configuration to analyze
+ * @returns The detected format type
+ */
+export declare function detectMappingFormat(input: UnifiedMappingInput): 'model-driven' | 'unified' | 'legacy';
+/**
+ * Main processor that unifies all JSON mapping formats into a consistent JsonMapping.
+ *
+ * Features:
+ * - Automatic format detection
+ * - Backward compatibility with all existing formats
+ * - Metadata preservation for advanced features
+ * - Zero external dependencies
+ *
+ * @param input - Any supported JSON mapping format
+ * @returns Unified processing result with JsonMapping and metadata
+ */
+export declare function processJsonMapping(input: UnifiedMappingInput): MappingProcessResult;
+/**
+ * Convenience function for direct JsonMapping extraction.
+ *
+ * @param input - Any supported JSON mapping format
+ * @returns JsonMapping ready for use with PostgresJsonQueryBuilder
+ */
+export declare function unifyJsonMapping(input: UnifiedMappingInput): JsonMapping;
+/**
+ * Type guard to check if input uses model-driven format.
+ *
+ * @param input - Mapping input to check
+ * @returns True if input is model-driven format
+ */
+export declare function isModelDrivenFormat(input: UnifiedMappingInput): input is ModelDrivenJsonMapping;
+/**
+ * Type guard to check if input uses unified format.
+ *
+ * @param input - Mapping input to check
+ * @returns True if input is unified format
+ */
+export declare function isUnifiedFormat(input: UnifiedMappingInput): boolean;
+/**
+ * Type guard to check if input uses legacy format.
+ *
+ * @param input - Mapping input to check
+ * @returns True if input is legacy format
+ */
+export declare function isLegacyFormat(input: UnifiedMappingInput): boolean;
+/**
+ * Migration helper that suggests upgrading to model-driven format.
+ *
+ * @param input - Current mapping configuration
+ * @returns Suggestions for migration (if applicable)
+ */
+export declare function suggestModelDrivenMigration(input: UnifiedMappingInput): string[];

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

@@ -0,0 +1,62 @@
+/**
+ * Model-driven JSON mapping structure that mirrors TypeScript model definitions.
+ * This approach provides intuitive, hierarchical mapping that closely resembles the target data structure.
+ */
+import { JsonMapping } from './PostgresJsonQueryBuilder';
+/**
+ * Supported field types for database column mapping.
+ */
+export type FieldType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'auto';
+/**
+ * Field mapping configuration that can be either a simple column name or enhanced mapping with type control.
+ */
+export type FieldMapping = string | {
+    column: string;
+    type?: FieldType;
+} | {
+    from: string;
+    type?: FieldType;
+};
+/**
+ * Nested object or array structure definition.
+ */
+export interface NestedStructure {
+    type: 'object' | 'array';
+    from: string;
+    structure: StructureFields;
+}
+/**
+ * Structure fields can contain either field mappings or nested structures.
+ */
+export type StructureFields = {
+    [key: string]: FieldMapping | NestedStructure;
+};
+/**
+ * Model-driven JSON mapping that mirrors TypeScript interface structure.
+ * This design makes it easy to understand the relationship between models and database columns.
+ */
+export interface ModelDrivenJsonMapping {
+    typeInfo: {
+        interface: string;
+        importPath: string;
+    };
+    structure: StructureFields;
+}
+/**
+ * Type protection configuration extracted from the model-driven mapping.
+ */
+export interface TypeProtectionConfig {
+    protectedStringFields: string[];
+}
+/**
+ * Convert a model-driven JSON mapping to the traditional JsonMapping format.
+ * This enables backward compatibility with existing PostgresJsonQueryBuilder.
+ */
+export declare function convertModelDrivenMapping(modelMapping: ModelDrivenJsonMapping): {
+    jsonMapping: JsonMapping;
+    typeProtection: TypeProtectionConfig;
+};
+/**
+ * Validate that a model-driven mapping structure is well-formed.
+ */
+export declare function validateModelDrivenMapping(mapping: ModelDrivenJsonMapping): string[];

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

@@ -90,8 +90,87 @@ export declare class PostgresArrayEntityCteBuilder {
      * @param entity The array entity being processed
      * @param nestedEntities All nested entities from the mapping
      * @param allEntities Map of all entities (not used in current implementation)
-     * @param useJsonb Whether to use JSONB functions
      * @returns Object containing the JSON aggregation function
      */
     private buildAggregationDetailsForArrayEntity;
+    /**
+     * Collects array entity columns organized by depth for the GROUP BY exclusion strategy.
+     *
+     * This method creates a mapping from depth levels to sets of column names that belong to
+     * array entities at each depth. This is used to determine which columns should be excluded
+     * from GROUP BY clauses when performing array aggregation at specific depths.
+     *
+     * @param mapping The JSON mapping configuration containing all entities
+     * @param currentDepth The current aggregation depth being processed
+     * @returns A map where keys are depth levels and values are sets of column names
+     */
+    private collectArrayEntityColumnsByDepth;
+    /**
+     * Calculates the depth of an entity in the hierarchy by traversing up to the root.
+     *
+     * @param entity The entity to calculate depth for
+     * @param mapping The JSON mapping containing all entities
+     * @returns The depth level (0 for root level, 1 for first level, etc.)
+     */
+    private calculateEntityDepth;
+    /**
+     * Adds all columns from an entity to the specified depth set.
+     *
+     * @param entity The entity whose columns should be added
+     * @param depth The depth level to add columns to
+     * @param arrayEntitiesByDepth The map to update
+     */
+    private addEntityColumnsToDepthSet;
+    /**
+     * Recursively collects columns from all descendant entities under a parent entity.
+     *
+     * This method ensures that all nested entities (at any depth) under an array entity
+     * have their columns properly categorized by the array entity's depth level.
+     *
+     * @param parentEntityId The ID of the parent entity
+     * @param targetDepth The depth level to assign collected columns to
+     * @param mapping The JSON mapping containing all entities
+     * @param arrayEntitiesByDepth The map to update with collected columns
+     */
+    private collectDescendantColumns;
+    /**
+     * Processes SELECT variables to determine which should be included in GROUP BY clauses.
+     *
+     * This method implements the core logic for deciding which columns from previous CTEs
+     * should be included in the GROUP BY clause when performing array aggregation. It handles
+     * special cases for JSON columns and applies depth-based filtering to prevent over-grouping.
+     *
+     * @param prevSelects SELECT variables from the previous CTE
+     * @param arrayColumns Columns that are being aggregated (should be excluded from GROUP BY)
+     * @param arrayEntitiesByDepth Map of depth levels to their column sets
+     * @param currentDepth The current aggregation depth being processed
+     * @param selectItems Output array for SELECT items
+     * @param groupByItems Output array for GROUP BY items
+     */
+    private processSelectVariablesForGroupBy;
+    /**
+     * Determines whether a column should be included in the GROUP BY clause.
+     *
+     * This method applies depth-based filtering and special handling for JSON columns
+     * to prevent over-grouping during array aggregation. It implements heuristics for
+     * excluding columns that belong to nested entities within array contexts.
+     *
+     * @param columnName The name of the column to evaluate
+     * @param arrayEntitiesByDepth Map of depth levels to their column sets
+     * @param currentDepth The current aggregation depth
+     * @returns True if the column should be included in GROUP BY, false otherwise
+     */
+    private shouldIncludeColumnInGroupBy;
+    /**
+     * Applies heuristics to determine if an entity JSON column should be included in GROUP BY.
+     *
+     * This method uses entity numbering patterns to identify deeply nested entities
+     * that should be excluded from GROUP BY when processing array aggregations.
+     * This is a simplified heuristic approach that works for current use cases.
+     *
+     * @param columnName The JSON column name (expected format: entity_N_json)
+     * @param currentDepth The current aggregation depth
+     * @returns True if the JSON column should be included, false otherwise
+     */
+    private shouldIncludeJsonColumn;
 }

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

@@ -1,4 +1,5 @@
 import { SimpleSelectQuery } from '../models/SimpleSelectQuery';
+import { SelectQuery } from '../models/SelectQuery';
 /**
  * Universal JSON mapping definition for creating any level of JSON structures.
  * Supports flat arrays, nested objects, and unlimited hierarchical structures.
@@ -22,7 +23,6 @@ export interface JsonMapping {
             [jsonKey: string]: string;
         };
     }>;
-    useJsonb?: boolean;
     resultFormat?: "array" | "single";
     emptyResult?: string;
 }
@@ -43,10 +43,11 @@ export declare class PostgresJsonQueryBuilder {
     private validateMapping;
     /**
      * Build JSON query from original query and mapping configuration.
-     * @param originalQuery Original query to transform
+     * @param originalQuery Original query to transform (can be any SelectQuery type)
      * @param mapping JSON mapping configuration
      * @returns Transformed query with JSON aggregation
      */
+    buildJsonQuery(originalQuery: SelectQuery, mapping: JsonMapping): SimpleSelectQuery;
     buildJsonQuery(originalQuery: SimpleSelectQuery, mapping: JsonMapping): SimpleSelectQuery;
     /**
      * Build JSON query from original query and mapping configuration.

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

@@ -20,12 +20,23 @@ import { SqlComponent, SqlComponentVisitor } from "../models/SqlComponent";
 import { ValueComponent } from "../models/ValueComponent";
 import { TableColumnResolver } from "./TableColumnResolver";
 /**
- * A visitor that collects all ColumnReference instances from a SQL query structure.
+ * A visitor that collects all ColumnReference instances from SimpleSelectQuery structures.
  * This visitor scans through all clauses and collects all unique ColumnReference objects.
  * It does not scan Common Table Expressions (CTEs) or subqueries.
  *
- * Important: Only collects column references to tables defined in the root FROM/JOIN clauses,
- * as these are the only columns that can be directly referenced in the query.
+ * IMPORTANT: This collector only supports SimpleSelectQuery. BinarySelectQuery
+ * (UNION/INTERSECT/EXCEPT) will throw an error and should be decomposed into
+ * individual SimpleSelectQuery branches before using this collector.
+ *
+ * Behavioral notes:
+ * - Only collects column references to tables defined in the root FROM/JOIN clauses
+ * - For aliased columns (e.g., 'title as name'), collects both the original column
+ *   reference ('title') AND the alias ('name') to enable complete dependency tracking
+ *
+ * Use cases:
+ * - Dependency analysis and schema migration tools
+ * - Column usage tracking within individual SELECT branches
+ * - Security analysis for column-level access control
  */
 export declare class SelectableColumnCollector implements SqlComponentVisitor<void> {
     private handlers;

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

@@ -26,8 +26,7 @@ export declare class SqlFormatter {
         keywordCase?: 'none' | 'upper' | 'lower';
         commaBreak?: CommaBreakStyle;
         andBreak?: AndBreakStyle;
-    });
-    /**
+    }); /**
      * Formats a SQL query string with the given parameters.
      * @param sqlText The SQL query string to format.
      * @param parameters A dictionary of parameters to replace in the query.
@@ -35,6 +34,6 @@ export declare class SqlFormatter {
      */
     format(sql: SqlComponent): {
         formattedSql: string;
-        params: Record<string, any>;
+        params: any[] | Record<string, any>;
     };
 }

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

@@ -0,0 +1,108 @@
+/**
+ * Post-processor for transforming database values to appropriate TypeScript types
+ * after JSON serialization from PostgreSQL
+ */
+export interface TypeTransformationConfig {
+    /** Column transformations mapping - takes precedence over value-based detection */
+    columnTransformations?: {
+        [columnName: string]: TypeTransformation;
+    };
+    /** Global transformation rules by SQL data type */
+    globalTransformations?: {
+        [sqlType: string]: TypeTransformation;
+    };
+    /** Custom transformation functions */
+    customTransformers?: {
+        [transformerName: string]: (value: any) => any;
+    };
+    /** Enable value-based type detection when column mapping is not provided (default: true) */
+    enableValueBasedDetection?: boolean;
+    /** Strict date detection - only convert ISO 8601 with 'T' separator (default: false) */
+    strictDateDetection?: boolean;
+}
+export interface TypeTransformation {
+    /** Source SQL data type */
+    sourceType: 'DATE' | 'TIMESTAMP' | 'BIGINT' | 'NUMERIC' | 'JSONB' | 'custom';
+    /** Target TypeScript type representation */
+    targetType: 'Date' | 'bigint' | 'string' | 'number' | 'object' | 'custom';
+    /** Custom transformer function name (for custom type) */
+    customTransformer?: string;
+    /** Whether to handle null values (default: true) */
+    handleNull?: boolean;
+    /** Validation function for the value */
+    validator?: (value: any) => boolean;
+}
+/**
+ * Applies type transformations to JSON results from PostgreSQL
+ */
+export declare class TypeTransformationPostProcessor {
+    private config;
+    constructor(config?: TypeTransformationConfig);
+    /**
+     * Transform a single result object
+     * @param result The result object from PostgreSQL JSON query
+     * @returns Transformed result with proper TypeScript types
+     */
+    transformResult<T = any>(result: any): T;
+    /**
+     * Transform a single object recursively
+     */
+    private transformSingleObject;
+    /**
+     * Detect value type and create appropriate transformation based on value characteristics
+     * This is the core value-based detection logic
+     */
+    private detectValueBasedTransformation;
+    /**
+     * Get global transformation for a specific value (if any match)
+     * This is separate from value-based detection and relies on configured global rules
+     */
+    private getGlobalTransformationForValue;
+    /**
+     * @deprecated Use detectValueBasedTransformation instead
+     * Detect value type and get appropriate global transformation
+     */
+    private detectAndGetGlobalTransformation;
+    /**
+     * Check if string is a valid date string
+     * Supports both strict (ISO 8601 with T separator) and loose detection
+     */
+    private isDateString;
+    /**
+     * Apply a specific transformation to a value
+     */
+    private applyTransformation;
+    /**
+     * Create a default configuration for common PostgreSQL types
+     * Enables value-based detection with loose date detection by default
+     */
+    static createDefaultConfig(): TypeTransformationConfig;
+    /**
+     * Create a safe configuration for handling user input
+     * Disables value-based detection and uses strict date detection
+     */
+    static createSafeConfig(columnMappings?: {
+        [columnName: string]: TypeTransformation;
+    }): TypeTransformationConfig;
+}
+/**
+ * Convenience function to create and apply transformations
+ */
+export declare function transformDatabaseResult<T = any>(result: any, config?: TypeTransformationConfig): T;
+/**
+ * Type-safe transformation helpers
+ */
+export declare const TypeTransformers: {
+    /**
+     * Transform date string to Date object
+     */
+    toDate: (value: string | null) => Date | null;
+    /**
+     * Transform numeric string to BigInt
+     */
+    toBigInt: (value: string | number | null) => bigint | null;
+    /**
+     * Transform JSON string to object
+     */
+    toObject: <T = any>(value: string | null) => T | null;
+};

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

@@ -0,0 +1,53 @@
+/**
+ * Enhanced JSON mapping structure that integrates column mapping and type protection configuration.
+ * This unified approach eliminates the need for separate .types.json files.
+ */
+import { JsonMapping } from './PostgresJsonQueryBuilder';
+/**
+ * Supported column type enforcement options.
+ */
+export type ColumnType = 'string' | 'auto';
+/**
+ * Column configuration that can either be a simple string mapping or an enhanced mapping with type control.
+ */
+export type ColumnMappingConfig = string | {
+    column: string;
+    type?: ColumnType;
+};
+/**
+ * Enhanced JSON mapping configuration with integrated type protection.
+ */
+export interface UnifiedJsonMapping {
+    rootName: string;
+    typeInfo?: {
+        interface: string;
+        importPath: string;
+    };
+    rootEntity: {
+        id: string;
+        name: string;
+        columns: Record<string, ColumnMappingConfig>;
+    };
+    nestedEntities?: Array<{
+        id: string;
+        name: string;
+        parentId: string;
+        propertyName: string;
+        relationshipType: 'object' | 'array';
+        columns: Record<string, ColumnMappingConfig>;
+    }>;
+}
+/**
+ * Type protection configuration extracted from the unified mapping.
+ */
+export interface TypeProtectionConfig {
+    protectedStringFields: string[];
+}
+/**
+ * Convert a unified JSON mapping to separate JsonMapping and TypeProtectionConfig.
+ * This enables backward compatibility with existing code while supporting the new unified structure.
+ */
+export declare function convertUnifiedMapping(unified: UnifiedJsonMapping): {
+    jsonMapping: JsonMapping;
+    typeProtection: TypeProtectionConfig;
+};

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

@@ -3,7 +3,11 @@ import { SelectQuery, SimpleSelectQuery } from "../models/SelectQuery";
  * UpstreamSelectQueryFinder searches upstream queries for the specified columns.
  * If a query (including its upstream CTEs or subqueries) contains all columns,
  * it returns the highest such SelectQuery. Otherwise, it searches downstream.
- * For UNION queries, it checks each branch independently.
+ *
+ * For BinarySelectQuery (UNION/INTERSECT/EXCEPT), this finder processes each branch
+ * independently, as SelectableColumnCollector is designed for SimpleSelectQuery only.
+ * This approach ensures accurate column detection within individual SELECT branches
+ * while maintaining compatibility with compound query structures.
  */
 export declare class UpstreamSelectQueryFinder {
     private options;