rawsql-ts 0.9.0-beta → 0.10.0-beta

package/dist/transformers/PostgresArrayEntityCteBuilder.d.ts

@@ -0,0 +1,97 @@
+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;
+}

package/dist/transformers/PostgresArrayEntityCteBuilder.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresArrayEntityCteBuilder = void 0;
+const Clause_1 = require("../models/Clause");
+const SimpleSelectQuery_1 = require("../models/SimpleSelectQuery");
+const ValueComponent_1 = require("../models/ValueComponent");
+const SelectValueCollector_1 = require("./SelectValueCollector");
+/**
+ * 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
+ */
+class PostgresArrayEntityCteBuilder {
+    /**
+     * 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, aliasOfCteToBuildUpon, allEntities, mapping) {
+        let currentCtes = [...ctesSoFar];
+        let currentCteAlias = aliasOfCteToBuildUpon;
+        // Collect and sort array entities by depth
+        const sortedArrayInfos = this.collectAndSortArrayEntities(mapping, allEntities);
+        if (sortedArrayInfos.length === 0) {
+            return { updatedCtes: currentCtes, lastCteAlias: currentCteAlias };
+        }
+        // Group array entities by depth level for batch processing
+        const entitiesByDepth = this.groupEntitiesByDepth(sortedArrayInfos);
+        // Process from deepest to shallowest (depth-first)
+        const depths = Array.from(entitiesByDepth.keys()).sort((a, b) => b - a);
+        for (const depth of depths) {
+            const infos = entitiesByDepth.get(depth);
+            // Build CTE for all entities at this depth
+            const { cte, newCteAlias } = this.buildDepthCte(infos, currentCteAlias, currentCtes, depth, mapping);
+            currentCtes.push(cte);
+            currentCteAlias = newCteAlias;
+        }
+        return { updatedCtes: currentCtes, lastCteAlias: currentCteAlias };
+    }
+    /**
+     * 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
+     */
+    collectAndSortArrayEntities(mapping, allEntities) {
+        const arrayEntityInfos = [];
+        // Helper function to calculate depth for an entity
+        const getDepth = (entityId) => {
+            const entity = allEntities.get(entityId);
+            if (!entity || entity.isRoot)
+                return 0;
+            if (!entity.parentId)
+                return 1;
+            return 1 + getDepth(entity.parentId);
+        };
+        // Collect all array-type nested entities
+        mapping.nestedEntities.forEach(ne => {
+            if (ne.relationshipType === "array") {
+                const currentArrayEntity = allEntities.get(ne.id);
+                const parentEntity = allEntities.get(ne.parentId);
+                if (!currentArrayEntity || !parentEntity) {
+                    throw new Error(`Configuration error: Array entity '${ne.id}' or its parent '${ne.parentId}' not found.`);
+                }
+                // Determine the linking column from parent entity
+                // This assumes the first column of the parent is a suitable key for linking.
+                // More robust linking might require explicit configuration in the mapping.
+                const parentSqlColumns = Object.values(parentEntity.columns);
+                if (parentSqlColumns.length === 0) {
+                    throw new Error(`Configuration error: Parent entity '${parentEntity.name}' (ID: ${parentEntity.id}) must have at least one column defined to serve as a linking key for child array '${ne.name}'.`);
+                }
+                const parentIdColumnSqlName = parentSqlColumns[0];
+                arrayEntityInfos.push({
+                    entity: currentArrayEntity,
+                    parentEntity: parentEntity,
+                    parentIdColumnSqlName: parentIdColumnSqlName,
+                    depth: getDepth(ne.id)
+                });
+            }
+        });
+        // Sort by depth, deepest arrays (higher depth number) processed first (bottom-up for arrays)
+        arrayEntityInfos.sort((a, b) => b.depth - a.depth);
+        return arrayEntityInfos;
+    }
+    /**
+     * 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
+     */
+    groupEntitiesByDepth(arrayInfos) {
+        const entitiesByDepth = new Map();
+        arrayInfos.forEach(info => {
+            const depth = info.depth;
+            if (!entitiesByDepth.has(depth)) {
+                entitiesByDepth.set(depth, []);
+            }
+            entitiesByDepth.get(depth).push(info);
+        });
+        return entitiesByDepth;
+    }
+    /**
+     * 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
+     */
+    buildDepthCte(infos, currentCteAlias, currentCtes, depth, mapping) {
+        var _a;
+        // Collect columns that will be compressed into arrays
+        const arrayColumns = new Set();
+        infos.forEach(info => {
+            Object.values(info.entity.columns).forEach(col => arrayColumns.add(col));
+        });
+        // Get columns from previous CTE
+        const prevCte = (_a = currentCtes.find(c => c.aliasExpression.table.name === currentCteAlias)) === null || _a === void 0 ? void 0 : _a.query;
+        if (!prevCte) {
+            throw new Error(`CTE not found: ${currentCteAlias}`);
+        }
+        const prevSelects = new SelectValueCollector_1.SelectValueCollector(null, currentCtes).collect(prevCte);
+        // Build SELECT items: columns that are NOT being compressed (for GROUP BY)
+        const groupByItems = [];
+        const selectItems = [];
+        prevSelects.forEach(sv => {
+            if (!arrayColumns.has(sv.name)) {
+                selectItems.push(new Clause_1.SelectItem(new ValueComponent_1.ColumnReference(null, new ValueComponent_1.IdentifierString(sv.name)), sv.name));
+                groupByItems.push(new ValueComponent_1.ColumnReference(null, new ValueComponent_1.IdentifierString(sv.name)));
+            }
+        });
+        // Add JSON aggregation columns for each array entity at this depth
+        for (const info of infos) {
+            const agg = this.buildAggregationDetailsForArrayEntity(info.entity, mapping.nestedEntities, new Map(), // allEntities - not needed for array aggregation
+            mapping.useJsonb);
+            selectItems.push(new Clause_1.SelectItem(agg.jsonAgg, info.entity.propertyName));
+        }
+        // Create the new CTE
+        const cteAlias = `${PostgresArrayEntityCteBuilder.CTE_ARRAY_PREFIX}${depth}`;
+        const cteSelect = new SimpleSelectQuery_1.SimpleSelectQuery({
+            selectClause: new Clause_1.SelectClause(selectItems),
+            fromClause: new Clause_1.FromClause(new Clause_1.SourceExpression(new Clause_1.TableSource(null, new ValueComponent_1.IdentifierString(currentCteAlias)), null), null),
+            groupByClause: groupByItems.length > 0 ? new Clause_1.GroupByClause(groupByItems) : null,
+        });
+        const cte = new Clause_1.CommonTable(cteSelect, new Clause_1.SourceAliasExpression(cteAlias, null), null);
+        return { cte, newCteAlias: cteAlias };
+    }
+    /**
+     * 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
+     */
+    buildAggregationDetailsForArrayEntity(entity, nestedEntities, allEntities, useJsonb = false) {
+        // Build JSON object for array elements
+        const jsonBuildFunction = useJsonb ? "jsonb_build_object" : "json_build_object";
+        const args = [];
+        // Add the entity's own columns
+        Object.entries(entity.columns).forEach(([jsonKey, sqlColumn]) => {
+            args.push(new ValueComponent_1.LiteralValue(jsonKey));
+            args.push(new ValueComponent_1.ColumnReference(null, new ValueComponent_1.IdentifierString(sqlColumn)));
+        });
+        // Find and process child entities (both object and array types)
+        const childEntities = nestedEntities.filter((ne) => ne.parentId === entity.id);
+        childEntities.forEach((childEntity) => {
+            args.push(new ValueComponent_1.LiteralValue(childEntity.propertyName));
+            if (childEntity.relationshipType === "object") {
+                // For object relationships, use pre-computed JSON column
+                const jsonColumnName = `${childEntity.name.toLowerCase()}_json`;
+                args.push(new ValueComponent_1.ColumnReference(null, new ValueComponent_1.IdentifierString(jsonColumnName)));
+            }
+            else if (childEntity.relationshipType === "array") {
+                // For array relationships, use the column directly
+                args.push(new ValueComponent_1.ColumnReference(null, new ValueComponent_1.IdentifierString(childEntity.propertyName)));
+            }
+        });
+        // Create JSON object
+        const jsonObject = new ValueComponent_1.FunctionCall(null, new ValueComponent_1.RawString(jsonBuildFunction), new ValueComponent_1.ValueList(args), null);
+        // Create JSON aggregation
+        const jsonAggFunction = useJsonb ? "jsonb_agg" : "json_agg";
+        const jsonAgg = new ValueComponent_1.FunctionCall(null, new ValueComponent_1.RawString(jsonAggFunction), new ValueComponent_1.ValueList([jsonObject]), null);
+        return { jsonAgg };
+    }
+}
+exports.PostgresArrayEntityCteBuilder = PostgresArrayEntityCteBuilder;
+// Constants for consistent naming conventions
+PostgresArrayEntityCteBuilder.CTE_ARRAY_PREFIX = 'cte_array_depth_';
+//# sourceMappingURL=PostgresArrayEntityCteBuilder.js.map

package/dist/transformers/PostgresArrayEntityCteBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PostgresArrayEntityCteBuilder.js","sourceRoot":"","sources":["../../src/transformers/PostgresArrayEntityCteBuilder.ts"],"names":[],"mappings":"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"}

package/dist/transformers/PostgresObjectEntityCteBuilder.d.ts

@@ -0,0 +1,140 @@
+import { CommonTable } from '../models/Clause';
+import { JsonMapping } from './PostgreJsonQueryBuilder';
+/**
+ * Entity with processing metadata
+ */
+export interface ProcessableEntity {
+    id: string;
+    name: string;
+    columns: {
+        [jsonKey: string]: string;
+    };
+    isRoot: boolean;
+    propertyName: string;
+    parentId?: string;
+    relationshipType?: "object" | "array";
+}
+/**
+ * PostgreSQL-specific builder for creating CTEs for object entities (object relationships).
+ * This class handles the creation of CTEs that build JSON/JSONB objects for object entities,
+ * processing them from the deepest level up to ensure proper dependency ordering.
+ *
+ * Features:
+ * - Depth-based CTE naming (cte_object_depth_N)
+ * - NULL handling for entity columns
+ * - JSONB/JSON object construction
+ * - Hierarchical processing of nested objects
+ *
+ * Why depth calculation is critical:
+ * 1. Object entities can be nested at multiple levels. We must process the deepest
+ *    (most distant) objects first to ensure their JSON representations are available
+ *    when building their parent entities.
+ * 2. Object entity processing is essentially a column compression operation. Entities
+ *    at the same depth level can be processed simultaneously since they don't depend
+ *    on each other.
+ *
+ * Example hierarchy:
+ * Order (root, depth 0)
+ *   └─ Customer (depth 1)
+ *       └─ Address (depth 2)
+ *   └─ Shipping (depth 1)
+ *       └─ Carrier (depth 2)
+ *
+ * Processing order: depth 2 → depth 1 → depth 0
+ */
+export declare class PostgresObjectEntityCteBuilder {
+    private static readonly JSON_COLUMN_SUFFIX;
+    private static readonly CTE_OBJECT_PREFIX;
+    private static readonly WILDCARD_COLUMN; /**
+     * Build CTEs for all object entities in the correct dependency order
+     * @param initialCte The starting CTE containing all raw data
+     * @param allEntities Map of all entities in the mapping
+     * @param mapping The JSON mapping configuration
+     * @returns Array of CTEs and the alias of the last CTE created
+     */
+    buildObjectEntityCtes(initialCte: CommonTable, allEntities: Map<string, ProcessableEntity>, mapping: JsonMapping): {
+        ctes: CommonTable[];
+        lastCteAlias: string;
+    }; /**
+     * Collect all object entities and calculate their depth from root.
+     *
+     * Depth calculation is crucial because:
+     * - It determines the processing order (deepest first)
+     * - It ensures dependencies are resolved before an entity is processed
+     * - It allows parallel processing of entities at the same depth level
+     *
+     * @param mapping The JSON mapping configuration
+     * @param allEntities Map of all entities in the mapping
+     * @returns Array of object entity information with calculated depths
+     */
+    private collectAndSortObjectEntities;
+    /**
+     * Group 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 parentInfos Array of parent entity information with depths
+     * @returns Map of depth level to entities at that depth
+     */ private groupEntitiesByDepth;
+    /**
+     * Build a CTE that processes all entities at a specific depth level
+     */
+    private buildDepthCte;
+    /**
+     * Build JSON column for a single entity with NULL handling
+     */
+    private buildEntityJsonColumn;
+    /**
+     * Prepare entity columns and NULL checks.
+     *
+     * This method extracts column data and creates NULL checks for each column.
+     * The NULL checking is essential for handling outer joins correctly.
+     *
+     * In outer join scenarios, when there's no matching row in the joined table,
+     * all columns from that table will be NULL. Instead of creating an empty object
+     * with all NULL properties (e.g., {id: null, name: null, email: null}),
+     * we want to represent the absence of the entity as NULL itself.
+     *
+     * This ensures cleaner JSON output where missing relationships are represented
+     * as NULL rather than objects with all NULL fields.
+     *
+     * @param entity The entity whose columns are being processed
+     * @returns Object containing arrays of JSON object arguments and NULL check conditions
+     */
+    private prepareEntityColumns;
+    /**
+     * Add child object relationships to JSON object arguments.
+     *
+     * This method processes nested object-type entities that are direct children of the current entity.
+     * For each child entity, it adds the property name and corresponding JSON column reference
+     * to the arguments array that will be used to build the parent's JSON object.
+     *
+     * The child JSON columns are expected to already exist in the data source (created by deeper
+     * level CTEs), as we process from the deepest level up to the root.
+     *
+     * Note: In this context, "child" refers to entities that have an object relationship (0..1)
+     * with their parent. From a data perspective, these are typically entities referenced via
+     * foreign keys, representing "parent" entities in traditional database terminology.
+     *
+     * @param entity The current entity being processed
+     * @param jsonObjectArgs Array to which JSON object arguments will be added
+     * @param mapping The JSON mapping configuration
+     * @param allEntities Map of all entities in the mapping
+     */
+    private addChildObjectRelationships;
+    /**
+     * Create JSON object function call
+     */
+    private createJsonObject;
+    /**
+     * Build NULL condition from NULL checks
+     */
+    private buildNullCondition;
+    /**
+     * Create CASE expression with NULL handling
+     */
+    private createCaseExpression;
+}