rawsql-ts 0.11.0-beta → 0.11.1-beta

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

@@ -23,7 +23,6 @@ export interface JsonMapping {
             [jsonKey: string]: string;
         };
     }>;
-    useJsonb?: boolean;
     resultFormat?: "array" | "single";
     emptyResult?: string;
 }

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/UnifiedJsonMapping.d.ts

@@ -36,7 +36,6 @@ export interface UnifiedJsonMapping {
         relationshipType: 'object' | 'array';
         columns: Record<string, ColumnMappingConfig>;
     }>;
-    useJsonb?: boolean;
 }
 /**
  * Type protection configuration extracted from the unified mapping.

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;