rawsql-ts 0.11.1-beta → 0.11.3-beta

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

@@ -19,4 +19,12 @@ export declare class ValueParser {
         value: ValueComponent;
         newIndex: number;
     };
+    /**
+     * Determines if a type token followed by parentheses is a type constructor or function call
+     * @param lexemes Array of lexemes
+     * @param openParenIndex Index of the opening parenthesis
+     * @param typeName Name of the type/function
+     * @returns True if this is a type constructor, false if it's a function call
+     */
+    private static isTypeConstructor;
 }

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

@@ -18,6 +18,12 @@ export interface QueryBuildOptions {
      * - false/undefined: no serialization
      */
     serialize?: JsonMapping | boolean;
+    /**
+     * JSONB usage setting. Must be true (default) for PostgreSQL GROUP BY compatibility.
+     * Setting to false will throw an error as JSON type cannot be used in GROUP BY clauses.
+     * @default true
+     */
+    jsonb?: boolean;
 }
 /**
  * DynamicQueryBuilder provides pure JavaScript SQL query building capabilities.

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

@@ -0,0 +1,194 @@
+/**
+ * Enhanced JSON mapping structure that extends the base JsonMapping interface
+ * with additional metadata and type safety features.
+ */
+/**
+ * Supported column types for enhanced mapping.
+ */
+export type ColumnType = 'string' | 'number' | 'boolean' | 'date' | 'auto';
+/**
+ * Enhanced column configuration that supports both simple and complex mappings.
+ */
+export interface ColumnConfig {
+    /** Source column name */
+    column: string;
+    /** Type enforcement for this column */
+    type?: ColumnType;
+    /** Whether this field is nullable */
+    nullable?: boolean;
+    /** Custom transformation function */
+    transform?: string;
+}
+/**
+ * Column mapping can be either a simple string or enhanced configuration.
+ */
+export type ColumnMapping = string | ColumnConfig;
+/**
+ * Enhanced entity definition with additional metadata.
+ */
+export interface EnhancedEntity {
+    id: string;
+    name: string;
+    columns: Record<string, ColumnMapping>;
+    /** Entity description for documentation */
+    description?: string;
+}
+/**
+ * Enhanced nested entity with relationship metadata.
+ */
+export interface EnhancedNestedEntity extends EnhancedEntity {
+    parentId: string;
+    propertyName: string;
+    relationshipType: 'object' | 'array';
+    /** Join condition for complex relationships */
+    joinCondition?: string;
+}
+/**
+ * Type protection configuration.
+ */
+export interface TypeProtectionConfig {
+    /** Columns that should be treated as strings */
+    protectedStringFields: string[];
+    /** Columns that should be parsed as dates */
+    dateFields?: string[];
+    /** Columns that should be parsed as numbers */
+    numberFields?: string[];
+    /** Custom type transformations */
+    customTransforms?: Record<string, string>;
+}
+/**
+ * Enhanced JSON mapping with type safety and metadata support.
+ */
+export interface EnhancedJsonMapping {
+    /** Root entity name */
+    rootName: string;
+    /** Root entity definition */
+    rootEntity: EnhancedEntity;
+    /** Nested entities */
+    nestedEntities: EnhancedNestedEntity[];
+    /** Result format */
+    resultFormat?: 'array' | 'single';
+    /** Empty result fallback */
+    emptyResult?: string;
+    /** Type information */
+    typeInfo?: {
+        interface: string;
+        importPath: string;
+        generics?: string[];
+    };
+    /** Type protection configuration */
+    typeProtection?: TypeProtectionConfig;
+    /** Mapping metadata */
+    metadata?: {
+        version: string;
+        description?: string;
+        author?: string;
+        createdAt?: string;
+        updatedAt?: string;
+    };
+}
+/**
+ * Legacy JSON mapping interface (from PostgresJsonQueryBuilder).
+ */
+export interface LegacyJsonMapping {
+    rootName: string;
+    rootEntity: {
+        id: string;
+        name: string;
+        columns: {
+            [jsonKey: string]: string;
+        };
+    };
+    nestedEntities: Array<{
+        id: string;
+        name: string;
+        parentId: string;
+        propertyName: string;
+        relationshipType?: "object" | "array";
+        columns: {
+            [jsonKey: string]: string;
+        };
+    }>;
+    resultFormat?: "array" | "single";
+    emptyResult?: string;
+}
+/**
+ * Converts enhanced column configurations to simple string mappings for legacy compatibility.
+ *
+ * This function transforms complex column configurations (with type info, nullable flags, etc.)
+ * into simple string mappings that can be used with PostgresJsonQueryBuilder.
+ *
+ * **Supported Input Formats:**
+ * - Simple strings: `"user_name"` → `"user_name"`
+ * - Column config: `{ column: "u.name", type: "string" }` → `"u.name"`
+ * - From config: `{ from: "user_name", nullable: true }` → `"user_name"`
+ *
+ * @param columns - Record of field names to column configurations
+ * @returns Record of field names to column source strings
+ *
+ * @example
+ * ```typescript
+ * const enhanced = {
+ *   id: { column: "u.user_id", type: "number" },
+ *   name: { from: "user_name", type: "string" },
+ *   email: "email_address"
+ * };
+ *
+ * const legacy = convertColumnsToLegacy(enhanced);
+ * // Result: { id: "u.user_id", name: "user_name", email: "email_address" }
+ * ```
+ */
+export declare function convertColumnsToLegacy(columns: Record<string, any>): Record<string, string>;
+/**
+ * Converts any unified JSON mapping format to legacy JsonMapping format.
+ *
+ * This universal converter handles Enhanced, Unified, and Legacy formats, providing
+ * a single interface for converting complex mapping configurations to the simple
+ * format expected by PostgresJsonQueryBuilder.
+ *
+ * **Supported Input Formats:**
+ * - **Enhanced**: With metadata, type protection, and advanced column configs
+ * - **Unified**: Standard format with rootName and rootEntity
+ * - **Legacy**: Already compatible format (returned as-is)
+ *
+ * **Features:**
+ * - Automatic format detection
+ * - Column configuration simplification
+ * - Nested entity handling
+ * - Type protection extraction
+ *
+ * @param input - JSON mapping in any supported format
+ * @returns Legacy JsonMapping compatible with PostgresJsonQueryBuilder
+ *
+ * @throws {Error} When input is null, undefined, or malformed
+ *
+ * @example
+ * ```typescript
+ * // Enhanced format input
+ * const enhanced = {
+ *   rootName: "User",
+ *   rootEntity: {
+ *     columns: {
+ *       id: { column: "u.user_id", type: "number" },
+ *       name: { column: "u.user_name", type: "string" }
+ *     }
+ *   },
+ *   metadata: { version: "2.0" }
+ * };
+ *
+ * const legacy = convertToLegacyJsonMapping(enhanced);
+ * // Result: Compatible with PostgresJsonQueryBuilder
+ * ```
+ *
+ * @see {@link convertColumnsToLegacy} For column-specific conversion
+ * @see {@link extractTypeProtection} For type safety features
+ */
+export declare function convertToLegacyJsonMapping(input: any): LegacyJsonMapping;
+/**
+ * Converts enhanced mapping to legacy format for backward compatibility.
+ */
+export declare function toLegacyMapping(enhanced: EnhancedJsonMapping): LegacyJsonMapping;
+/**
+ * Extracts type protection configuration from enhanced mapping.
+ */
+export declare function extractTypeProtection(enhanced: EnhancedJsonMapping): TypeProtectionConfig;

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

@@ -0,0 +1,200 @@
+/**
+ * Unified JSON mapping converter that handles all supported formats
+ * and provides a single interface for mapping transformations.
+ */
+import { JsonMapping } from './PostgresJsonQueryBuilder';
+import { ModelDrivenJsonMapping } from './ModelDrivenJsonMapping';
+import { EnhancedJsonMapping, LegacyJsonMapping, TypeProtectionConfig } from './EnhancedJsonMapping';
+/**
+ * Input format types that the converter can handle.
+ */
+export type JsonMappingInput = EnhancedJsonMapping | ModelDrivenJsonMapping | LegacyJsonMapping;
+/**
+ * Format detection result.
+ */
+export type MappingFormat = 'enhanced' | 'model-driven' | 'legacy';
+/**
+ * Conversion result with metadata.
+ */
+export interface ConversionResult {
+    /** Detected input format */
+    format: MappingFormat;
+    /** Converted legacy mapping for PostgresJsonQueryBuilder */
+    mapping: JsonMapping;
+    /** Type protection configuration */
+    typeProtection: TypeProtectionConfig;
+    /** Original input for reference */
+    originalInput: JsonMappingInput;
+    /** Additional metadata */
+    metadata?: {
+        typeInfo?: {
+            interface: string;
+            importPath: string;
+            generics?: string[];
+        };
+        version?: string;
+        description?: string;
+    };
+}
+/**
+ * Unified JSON mapping converter that handles all supported formats using the Strategy pattern.
+ *
+ * This converter automatically detects the input format and applies the appropriate conversion
+ * strategy to transform any supported JSON mapping format into a standardized result.
+ *
+ * **Supported Formats:**
+ * - **Enhanced**: Rich format with metadata, type protection, and advanced column configurations
+ * - **Model-Driven**: TypeScript interface-based mapping with structured field definitions
+ * - **Legacy**: Simple format compatible with PostgresJsonQueryBuilder
+ *
+ * **Usage:**
+ * ```typescript
+ * const converter = new JsonMappingConverter();
+ * const result = converter.convert(someMapping);
+ * const legacyMapping = converter.toLegacyMapping(someMapping);
+ * ```
+ *
+ * @public
+ */
+export declare class JsonMappingConverter {
+    /** Ordered list of conversion strategies, checked in priority order */
+    private strategies;
+    /**
+     * Creates a new JsonMappingConverter with all supported strategies.
+     *
+     * Strategies are checked in order of specificity:
+     * 1. Enhanced format (most feature-rich)
+     * 2. Model-driven format (TypeScript-based)
+     * 3. Legacy format (fallback)
+     */
+    constructor();
+    /**
+     * Detects the format of the input mapping without performing conversion.
+     *
+     * This method uses the same strategy pattern as conversion but only returns
+     * the detected format type for inspection purposes.
+     *
+     * @param input - The JSON mapping to analyze
+     * @returns The detected mapping format type
+     *
+     * @throws {Error} When input format is not supported by any strategy
+     *
+     * @example
+     * ```typescript
+     * const format = converter.detectFormat(myMapping);
+     * console.log(`Detected format: ${format}`); // "enhanced", "model-driven", or "legacy"
+     * ```
+     */
+    detectFormat(input: JsonMappingInput): MappingFormat;
+    /**
+     * Converts any supported JSON mapping format to a comprehensive result with metadata.
+     *
+     * This is the primary conversion method that performs format detection and transformation
+     * in a single operation. The result includes the legacy mapping, type protection configuration,
+     * and metadata about the conversion process.
+     *
+     * @param input - The JSON mapping in any supported format (Enhanced, Model-Driven, or Legacy)
+     * @returns Complete conversion result with mapping, metadata, and type protection
+     *
+     * @throws {Error} When the input format is not recognized by any strategy
+     *
+     * @example
+     * ```typescript
+     * const result = converter.convert(enhancedMapping);
+     * console.log(`Format: ${result.format}`);
+     * console.log(`Type protection: ${result.typeProtection.protectedStringFields.length} fields`);
+     *
+     * // Use the converted mapping
+     * const queryBuilder = new PostgresJsonQueryBuilder(result.mapping);
+     * ```
+     *
+     * @see {@link toLegacyMapping} For simple mapping extraction
+     * @see {@link getTypeProtection} For type protection only
+     */
+    convert(input: JsonMappingInput): ConversionResult;
+    /**
+     * Extracts only the legacy JsonMapping for direct use with PostgresJsonQueryBuilder.
+     *
+     * This convenience method performs the full conversion but returns only the mapping portion,
+     * discarding metadata and type protection information. Use this when you only need
+     * the mapping for query building and don't require additional metadata.
+     *
+     * @param input - The JSON mapping in any supported format
+     * @returns Legacy-format JsonMapping ready for PostgresJsonQueryBuilder
+     *
+     * @throws {Error} When the input format is not supported
+     *
+     * @example
+     * ```typescript
+     * const legacyMapping = converter.toLegacyMapping(modelDrivenMapping);
+     * const queryBuilder = new PostgresJsonQueryBuilder(legacyMapping);
+     * const query = queryBuilder.build(selectQuery);
+     * ```
+     *
+     * @see {@link convert} For full conversion with metadata
+     */
+    toLegacyMapping(input: JsonMappingInput): JsonMapping;
+    /**
+     * Extracts type protection configuration for runtime type checking.
+     *
+     * Type protection helps identify fields that should be treated as strings
+     * to prevent injection attacks or type coercion issues. This is particularly
+     * useful when working with user input or external data sources.
+     *
+     * @param input - The JSON mapping in any supported format
+     * @returns Type protection configuration with protected field definitions
+     *
+     * @throws {Error} When the input format is not supported
+     *
+     * @example
+     * ```typescript
+     * const typeProtection = converter.getTypeProtection(enhancedMapping);
+     *
+     * // Apply type protection during data processing
+     * for (const field of typeProtection.protectedStringFields) {
+     *     if (typeof data[field] !== 'string') {
+     *         data[field] = String(data[field]);
+     *     }
+     * }
+     * ```
+     */
+    getTypeProtection(input: JsonMappingInput): TypeProtectionConfig;
+    /**
+     * Validates that the input mapping is well-formed and can be successfully converted.
+     *
+     * This method performs comprehensive validation without attempting conversion,
+     * returning an array of error messages for any issues found. An empty array
+     * indicates the mapping is valid and ready for conversion.
+     *
+     * **Validation Checks:**
+     * - Basic structure validation (object type, required fields)
+     * - Format-specific validation (Enhanced, Model-Driven, Legacy)
+     * - Column configuration validation
+     * - Type protection configuration validation
+     *
+     * @param input - The JSON mapping to validate
+     * @returns Array of validation error messages (empty if valid)
+     *
+     * @example
+     * ```typescript
+     * const errors = converter.validate(suspiciousMapping);
+     * if (errors.length > 0) {
+     *     console.error('Validation failed:', errors);
+     *     throw new Error(`Invalid mapping: ${errors.join(', ')}`);
+     * }
+     *
+     * // Safe to convert
+     * const result = converter.convert(suspiciousMapping);
+     * ```
+     *
+     * @see {@link convert} Performs conversion after implicit validation
+     */
+    validate(input: JsonMappingInput): string[];
+    /**
+     * Creates a new enhanced mapping from legacy mapping.
+     */
+    upgradeToEnhanced(legacy: LegacyJsonMapping, typeInfo?: {
+        interface: string;
+        importPath: string;
+    }): EnhancedJsonMapping;
+}

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

@@ -1,6 +1,7 @@
 /**
  * Unified JSON Mapping processor that supports both legacy and model-driven formats.
  *
+ * @deprecated Use JsonMappingConverter instead. This module is kept for backward compatibility.
  * 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.
  */
@@ -48,6 +49,8 @@ export declare function detectMappingFormat(input: UnifiedMappingInput): 'model-
 /**
  * Main processor that unifies all JSON mapping formats into a consistent JsonMapping.
  *
+ * @deprecated Use JsonMappingConverter.convert() instead.
+ *
  * Features:
  * - Automatic format detection
  * - Backward compatibility with all existing formats
@@ -61,6 +64,8 @@ export declare function processJsonMapping(input: UnifiedMappingInput): MappingP
 /**
  * Convenience function for direct JsonMapping extraction.
  *
+ * @deprecated Use JsonMappingConverter.toLegacyMapping() instead.
+ *
  * @param input - Any supported JSON mapping format
  * @returns JsonMapping ready for use with PostgresJsonQueryBuilder
  */

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

@@ -1,104 +1,77 @@
 import { CommonTable } from '../models/Clause';
 import { JsonMapping } from './PostgresJsonQueryBuilder';
-import { ProcessableEntity } from './PostgresObjectEntityCteBuilder';
+import { ProcessableEntity, JsonColumnMapping } 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.
+ * Builds CTEs for array entities using depth-first processing and row compression.
  *
- * 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
+ * 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;
     /**
-     * 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
+     * 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
-     * @returns Object containing the updated list of all CTEs and the alias of the last CTE created
+     * @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): {
+    buildArrayEntityCtes(ctesSoFar: CommonTable[], aliasOfCteToBuildUpon: string, allEntities: Map<string, ProcessableEntity>, mapping: JsonMapping, columnMappings?: JsonColumnMapping[]): {
         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.
+     * 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 calculated depths, sorted deepest first
+     * @returns Array of array entity information with 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
+     * 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;
     /**
-     * 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.
+     * 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;
     /**
-     * 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.
+     * 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 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.
+     * 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
@@ -106,7 +79,7 @@ export declare class PostgresArrayEntityCteBuilder {
      */
     private collectArrayEntityColumnsByDepth;
     /**
-     * Calculates the depth of an entity in the hierarchy by traversing up to the root.
+     * Calculates entity depth by traversing up to root.
      *
      * @param entity The entity to calculate depth for
      * @param mapping The JSON mapping containing all entities
@@ -114,7 +87,7 @@ export declare class PostgresArrayEntityCteBuilder {
      */
     private calculateEntityDepth;
     /**
-     * Adds all columns from an entity to the specified depth set.
+     * Adds entity columns to depth set.
      *
      * @param entity The entity whose columns should be added
      * @param depth The depth level to add columns to
@@ -122,10 +95,7 @@ export declare class PostgresArrayEntityCteBuilder {
      */
     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.
+     * Recursively collects columns from descendant entities.
      *
      * @param parentEntityId The ID of the parent entity
      * @param targetDepth The depth level to assign collected columns to
@@ -134,11 +104,8 @@ export declare class PostgresArrayEntityCteBuilder {
      */
     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.
+     * 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)
@@ -146,14 +113,12 @@ export declare class PostgresArrayEntityCteBuilder {
      * @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 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.
+     * 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
@@ -162,11 +127,8 @@ export declare class PostgresArrayEntityCteBuilder {
      */
     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.
+     * 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

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

@@ -1,5 +1,6 @@
 import { SimpleSelectQuery } from '../models/SimpleSelectQuery';
 import { SelectQuery } from '../models/SelectQuery';
+import { QueryBuildOptions } from './DynamicQueryBuilder';
 /**
  * Universal JSON mapping definition for creating any level of JSON structures.
  * Supports flat arrays, nested objects, and unlimited hierarchical structures.
@@ -47,8 +48,8 @@ export declare class PostgresJsonQueryBuilder {
      * @param mapping JSON mapping configuration
      * @returns Transformed query with JSON aggregation
      */
-    buildJsonQuery(originalQuery: SelectQuery, mapping: JsonMapping): SimpleSelectQuery;
-    buildJsonQuery(originalQuery: SimpleSelectQuery, mapping: JsonMapping): SimpleSelectQuery;
+    buildJsonQuery(originalQuery: SelectQuery, mapping: JsonMapping, options?: QueryBuildOptions): SimpleSelectQuery;
+    buildJsonQuery(originalQuery: SimpleSelectQuery, mapping: JsonMapping, options?: QueryBuildOptions): SimpleSelectQuery;
     /**
      * Build JSON query from original query and mapping configuration.
      * @deprecated Use buildJsonQuery instead. This method will be removed in a future version.