rawsql-ts/dist/transformers/PostgresArrayEntityCteBuilder.d.ts

[beta]High-performance SQL parser and AST analyzer written in TypeScript. Provides fast parsing and advanced transformation capabilities.

import { CommonTable } from '../models/Clause';
import { JsonMapping } from './PostgreJsonQueryBuilder';
import { ProcessableEntity } from './PostgresObjectEntityCteBuilder';
/**
 * PostgreSQL-specific builder for creating CTEs for array entities (array relationships).
 * This class handles the creation of CTEs that build JSON/JSONB arrays for child entities,
 * processing them from the deepest level up to ensure proper dependency ordering.
 *
 * Features:
 * - Depth-based CTE naming (cte_array_depth_N)
 * - Row compression using GROUP BY operations
 * - JSONB/JSON array aggregation
 * - Hierarchical processing of nested arrays
 * - Column exclusion to avoid duplication
 *
 * Why depth calculation is critical:
 * 1. Array entities can be nested at multiple levels. We must process the deepest
 *    (most distant) arrays first to ensure their JSON representations are available
 *    when building their parent arrays.
 * 2. Array entity processing is essentially a row compression operation using GROUP BY.
 *    Unlike parent entities which use column compression, arrays require grouping
 *    to aggregate multiple rows into JSON arrays.
 *
 * Example hierarchy:
 * Order (root, depth 0)
 *   └─ Items (array, depth 1)
 *       └─ Details (array, depth 2)
 *
 * Processing order: depth 2 → depth 1 → depth 0
 */
export declare class PostgresArrayEntityCteBuilder {
    private static readonly CTE_ARRAY_PREFIX;
    /**
     * Build CTEs for all array entities in the correct dependency order
     * @param ctesSoFar Array of CTEs built so far (starts with the initial CTE)
     * @param aliasOfCteToBuildUpon Alias of the CTE from which the current array CTE will select
     * @param allEntities Map of all entities in the mapping
     * @param mapping The JSON mapping configuration
     * @returns Object containing the updated list of all CTEs and the alias of the last CTE created
     */
    buildArrayEntityCtes(ctesSoFar: CommonTable[], aliasOfCteToBuildUpon: string, allEntities: Map<string, ProcessableEntity>, mapping: JsonMapping): {
        updatedCtes: CommonTable[];
        lastCteAlias: string;
    };
    /**
     * Collect all array entities and calculate their depth from root.
     *
     * Depth calculation ensures proper processing order where deeper nested
     * arrays are processed first, making their aggregated data available
     * for parent array processing.
     *
     * @param mapping The JSON mapping configuration
     * @param allEntities Map of all entities in the mapping
     * @returns Array of array entity information with calculated depths, sorted deepest first
     */
    private collectAndSortArrayEntities;
    /**
     * Group array entities by their depth level.
     *
     * Grouping by depth allows us to:
     * - Process all entities at the same level in a single CTE
     * - Optimize query performance by reducing the number of CTEs
     * - Maintain clear dependency ordering
     *
     * @param arrayInfos Array of array entity information with depths
     * @returns Map of depth level to entities at that depth
     */
    private groupEntitiesByDepth;
    /**
     * Build a CTE that processes all array entities at a specific depth level.
     *
     * This method creates a single CTE that aggregates multiple array entities
     * at the same depth, using GROUP BY to compress rows into JSON arrays.
     *
     * @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
     * @returns The new CTE and its alias
     */
    private buildDepthCte;
    /**
     * Build JSON aggregation function for an array entity.
     *
     * This method creates a jsonb_agg or json_agg function call that aggregates
     * the entity's columns into a JSON array. It also handles nested relationships
     * by including child entity properties in the JSON object.
     *
     * @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;
}