rawsql-ts
Version:
[beta]High-performance SQL parser and AST analyzer written in TypeScript. Provides fast parsing and advanced transformation capabilities.
139 lines (138 loc) • 6.54 kB
TypeScript
import { CommonTable } from '../models/Clause';
import { JsonMapping } from './PostgresJsonQueryBuilder';
import { ProcessableEntity, JsonColumnMapping } from './PostgresObjectEntityCteBuilder';
/**
* Builds CTEs for array entities using depth-first processing and row compression.
*
* Core concepts:
* - Column Compression: OBJECT relationships (user_id, user_name → user_json)
* - Row Compression: ARRAY relationships (multiple rows → JSON array via GROUP BY)
* - Depth-First: Process deepest arrays first for dependency ordering
* - GROUP BY Exclusion: Exclude array-internal columns to prevent over-grouping
*/
export declare class PostgresArrayEntityCteBuilder {
private static readonly CTE_ARRAY_PREFIX;
private static readonly JSON_FUNCTIONS;
/**
* Builds CTEs for all array entities using depth-first processing.
* Collects arrays by depth, processes deepest first, chains CTEs.
*
* @param ctesSoFar Array of CTEs built so far
* @param aliasOfCteToBuildUpon Alias of the CTE to build upon
* @param allEntities Map of all entities in the mapping
* @param mapping The JSON mapping configuration
* @param columnMappings Optional mappings from object entity IDs to generated JSON column names
* @returns Object containing updated CTEs and last CTE alias
*/
buildArrayEntityCtes(ctesSoFar: CommonTable[], aliasOfCteToBuildUpon: string, allEntities: Map<string, ProcessableEntity>, mapping: JsonMapping, columnMappings?: JsonColumnMapping[]): {
updatedCtes: CommonTable[];
lastCteAlias: string;
};
/**
* Collects array entities and calculates depth for dependency ordering.
* Depth = distance from root. Deeper arrays processed first.
*
* @param mapping The JSON mapping configuration
* @param allEntities Map of all entities in the mapping
* @returns Array of array entity information with depths, sorted deepest first
*/
private collectAndSortArrayEntities;
/**
* Groups array entities by depth level for batch processing.
*
* @param arrayInfos Array of array entity information with depths
* @returns Map of depth level to entities at that depth
*/
private groupEntitiesByDepth;
/**
* Builds CTE for specific depth level using row compression.
* Uses GROUP BY to aggregate multiple rows into JSON arrays.
* Excludes array-internal columns from GROUP BY to prevent over-grouping.
*
* @param infos Array entities at this depth level
* @param currentCteAlias Alias of the CTE to build upon
* @param currentCtes All CTEs built so far
* @param depth Current depth level being processed
* @param mapping JSON mapping configuration
* @param columnMappings Optional mappings from object entity IDs to generated JSON column names
* @returns The new CTE and its alias
*/
private buildDepthCte;
/**
* Creates jsonb_agg function for array entity.
* Handles entity columns and nested child relationships.
* Uses originalPropertyName to avoid sequential numbering.
*
* @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 columnMappings Mappings from object entity IDs to generated JSON column names
* @returns Object containing the JSON aggregation function
*/
private buildAggregationDetailsForArrayEntity;
/**
* Collects array entity columns by depth for GROUP BY exclusion strategy.
*
* @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 entity depth by traversing up to 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 entity columns to 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 descendant entities.
*
* @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;
/**
* Implements GROUP BY exclusion strategy for array aggregation.
* Excludes current array columns and array-internal object JSON columns.
*
* @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
* @param arrayInternalObjectColumns JSON columns from objects within arrays being processed
*/
private processSelectVariablesForGroupBy;
/**
* Determines if column should be included in GROUP BY clause.
* Applies depth-based filtering and special handling for JSON columns.
*
* @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 for entity JSON column inclusion in GROUP BY.
* Uses entity numbering patterns to identify deeply nested entities.
*
* @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;
}