rawsql-ts 0.10.9-beta → 0.11.1-beta

package/dist/src/transformers/DynamicQueryBuilder.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamicQueryBuilder = void 0;
+const SelectQueryParser_1 = require("../parsers/SelectQueryParser");
+const SqlParamInjector_1 = require("./SqlParamInjector");
+const SqlSortInjector_1 = require("./SqlSortInjector");
+const SqlPaginationInjector_1 = require("./SqlPaginationInjector");
+const PostgresJsonQueryBuilder_1 = require("./PostgresJsonQueryBuilder");
+const QueryBuilder_1 = require("./QueryBuilder");
+/**
+ * DynamicQueryBuilder provides pure JavaScript SQL query building capabilities.
+ * It combines SQL parsing with dynamic condition injection (filtering, sorting, pagination, serialization).
+ *
+ * This class is framework-agnostic and does not perform any file I/O operations.
+ * It only works with SQL content provided as strings.
+ *
+ * Key features:
+ * - Pure JavaScript/TypeScript - no file system dependencies
+ * - Framework-agnostic - can be used with any database framework
+ * - Composable - combines multiple injectors in the correct order
+ * - Type-safe - provides TypeScript types for all options
+ * - Testable - easy to unit test without mocking file system
+ */
+class DynamicQueryBuilder {
+    /**
+     * Creates a new DynamicQueryBuilder instance
+     * @param tableColumnResolver Optional function to resolve table columns for wildcard queries
+     */
+    constructor(tableColumnResolver) {
+        this.tableColumnResolver = tableColumnResolver;
+    }
+    /**
+     * Builds a SelectQuery from SQL content with dynamic conditions.
+     * This is a pure function that does not perform any I/O operations.
+     *     * @param sqlContent Raw SQL string to parse and modify
+     * @param options Dynamic conditions to apply (filter, sort, paging, serialize)
+     * @returns Modified SelectQuery with all dynamic conditions applied
+     *     * @example
+     * ```typescript
+     * const builder = new DynamicQueryBuilder();
+     * const query = builder.buildQuery(
+     *   'SELECT id, name FROM users WHERE active = true',
+     *   {
+     *     filter: { status: 'premium' },
+     *     sort: { created_at: { desc: true } },
+     *     paging: { page: 2, pageSize: 10 },
+     *     serialize: { rootName: 'user', rootEntity: { id: 'user', name: 'User', columns: { id: 'id', name: 'name' } }, nestedEntities: [] }
+     *   }
+     * );
+     * ```
+     */
+    buildQuery(sqlContent, options = {}) {
+        // Parse the base SQL
+        let parsedQuery;
+        try {
+            parsedQuery = SelectQueryParser_1.SelectQueryParser.parse(sqlContent);
+        }
+        catch (error) {
+            throw new Error(`Failed to parse SQL: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+        // Apply dynamic modifications in the correct order
+        let modifiedQuery = parsedQuery;
+        // 1. Apply filtering first (most selective, should reduce data early)
+        if (options.filter && Object.keys(options.filter).length > 0) {
+            const paramInjector = new SqlParamInjector_1.SqlParamInjector(this.tableColumnResolver);
+            // Ensure we have a SimpleSelectQuery for the injector
+            const simpleQuery = QueryBuilder_1.QueryBuilder.buildSimpleQuery(modifiedQuery);
+            modifiedQuery = paramInjector.inject(simpleQuery, options.filter);
+        }
+        // 2. Apply sorting second (after filtering to sort smaller dataset)
+        if (options.sort && Object.keys(options.sort).length > 0) {
+            const sortInjector = new SqlSortInjector_1.SqlSortInjector(this.tableColumnResolver);
+            // Ensure we have a SimpleSelectQuery for the injector
+            const simpleQuery = QueryBuilder_1.QueryBuilder.buildSimpleQuery(modifiedQuery);
+            modifiedQuery = sortInjector.inject(simpleQuery, options.sort);
+        } // 3. Apply pagination third (after filtering and sorting)
+        if (options.paging) {
+            const { page = 1, pageSize } = options.paging;
+            if (pageSize !== undefined) {
+                const paginationInjector = new SqlPaginationInjector_1.SqlPaginationInjector();
+                const paginationOptions = { page, pageSize };
+                // Ensure we have a SimpleSelectQuery for the injector
+                const simpleQuery = QueryBuilder_1.QueryBuilder.buildSimpleQuery(modifiedQuery);
+                modifiedQuery = paginationInjector.inject(simpleQuery, paginationOptions);
+            }
+        }
+        // 4. Apply serialization last (transform the final query structure to JSON)
+        // Note: boolean values are handled at RawSqlClient level for auto-loading
+        if (options.serialize && typeof options.serialize === 'object') {
+            const jsonBuilder = new PostgresJsonQueryBuilder_1.PostgresJsonQueryBuilder();
+            // Ensure we have a SimpleSelectQuery for the JSON builder
+            const simpleQuery = QueryBuilder_1.QueryBuilder.buildSimpleQuery(modifiedQuery);
+            modifiedQuery = jsonBuilder.buildJsonQuery(simpleQuery, options.serialize);
+        }
+        return modifiedQuery;
+    }
+    /**
+     * Builds a SelectQuery with only filtering applied.
+     * Convenience method for when you only need dynamic WHERE conditions.
+     *
+     * @param sqlContent Raw SQL string to parse and modify
+     * @param filter Filter conditions to apply
+     * @returns Modified SelectQuery with filter conditions applied
+     */
+    buildFilteredQuery(sqlContent, filter) {
+        return this.buildQuery(sqlContent, { filter });
+    }
+    /**
+     * Builds a SelectQuery with only sorting applied.
+     * Convenience method for when you only need dynamic ORDER BY clauses.
+     *
+     * @param sqlContent Raw SQL string to parse and modify
+     * @param sort Sort conditions to apply
+     * @returns Modified SelectQuery with sort conditions applied
+     */
+    buildSortedQuery(sqlContent, sort) {
+        return this.buildQuery(sqlContent, { sort });
+    } /**
+     * Builds a SelectQuery with only pagination applied.
+     * Convenience method for when you only need LIMIT/OFFSET clauses.
+     *
+     * @param sqlContent Raw SQL string to parse and modify
+     * @param paging Pagination options to apply
+     * @returns Modified SelectQuery with pagination applied
+     */
+    buildPaginatedQuery(sqlContent, paging) {
+        return this.buildQuery(sqlContent, { paging });
+    }
+    /**
+     * Builds a SelectQuery with only JSON serialization applied.
+     * Convenience method for when you only need hierarchical JSON transformation.
+     *
+     * @param sqlContent Raw SQL string to parse and modify
+     * @param serialize JSON mapping configuration to apply
+     * @returns Modified SelectQuery with JSON serialization applied
+     */
+    buildSerializedQuery(sqlContent, serialize) {
+        return this.buildQuery(sqlContent, { serialize });
+    }
+    /**
+     * Validates SQL content by attempting to parse it.
+     * Useful for testing SQL validity without applying any modifications.
+     *
+     * @param sqlContent Raw SQL string to validate
+     * @returns true if SQL is valid, throws error if invalid
+     * @throws Error if SQL cannot be parsed
+     */
+    validateSql(sqlContent) {
+        try {
+            SelectQueryParser_1.SelectQueryParser.parse(sqlContent);
+            return true;
+        }
+        catch (error) {
+            throw new Error(`Invalid SQL: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+}
+exports.DynamicQueryBuilder = DynamicQueryBuilder;
+//# sourceMappingURL=DynamicQueryBuilder.js.map

package/dist/src/transformers/DynamicQueryBuilder.js.map

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

package/dist/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/src/transformers/JsonMappingUnifier.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectMappingFormat = detectMappingFormat;
+exports.processJsonMapping = processJsonMapping;
+exports.unifyJsonMapping = unifyJsonMapping;
+exports.isModelDrivenFormat = isModelDrivenFormat;
+exports.isUnifiedFormat = isUnifiedFormat;
+exports.isLegacyFormat = isLegacyFormat;
+exports.suggestModelDrivenMigration = suggestModelDrivenMigration;
+const ModelDrivenJsonMapping_1 = require("./ModelDrivenJsonMapping");
+/**
+ * Detects the format of a JSON mapping configuration.
+ *
+ * @param input - The mapping configuration to analyze
+ * @returns The detected format type
+ */
+function detectMappingFormat(input) {
+    // Model-driven format: has typeInfo and structure
+    if (input.typeInfo && input.structure) {
+        return 'model-driven';
+    }
+    // Unified format: has rootName and rootEntity
+    if (input.rootName && input.rootEntity) {
+        return 'unified';
+    }
+    // Legacy format: direct JsonMapping structure
+    if (input.columns || input.relationships) {
+        return 'legacy';
+    }
+    // Default fallback
+    return 'legacy';
+}
+/**
+ * Converts legacy unified format to JsonMapping.
+ *
+ * @param input - Unified format mapping configuration
+ * @returns Converted JsonMapping
+ */
+function convertUnifiedFormat(input) {
+    if (!input.rootEntity) {
+        throw new Error('Unified format requires rootEntity');
+    }
+    const result = {
+        rootName: input.rootName || 'root',
+        rootEntity: {
+            id: input.rootEntity.id || 'root',
+            name: input.rootEntity.name || 'Root',
+            columns: input.rootEntity.columns || {}
+        },
+        nestedEntities: []
+    };
+    // Convert nestedEntities
+    if (input.nestedEntities && Array.isArray(input.nestedEntities)) {
+        result.nestedEntities = input.nestedEntities.map(entity => ({
+            id: entity.id || entity.propertyName || 'nested',
+            name: entity.name || entity.propertyName || 'Nested',
+            parentId: entity.parentId || result.rootEntity.id,
+            propertyName: entity.propertyName || 'nested',
+            relationshipType: entity.relationshipType || 'object',
+            columns: entity.columns || {}
+        }));
+    }
+    return result;
+}
+/**
+ * Converts legacy format directly to JsonMapping.
+ *
+ * @param input - Legacy format mapping configuration
+ * @returns JsonMapping
+ */
+function convertLegacyFormat(input) {
+    const result = {
+        rootName: input.rootName || 'root',
+        rootEntity: {
+            id: 'root',
+            name: input.rootName || 'Root',
+            columns: input.columns || {}
+        },
+        nestedEntities: []
+    };
+    // Convert relationships to nestedEntities
+    if (input.relationships && typeof input.relationships === 'object') {
+        for (const [propertyName, relationship] of Object.entries(input.relationships)) {
+            // Type assertion for legacy relationship format
+            const rel = relationship;
+            result.nestedEntities.push({
+                id: propertyName,
+                name: propertyName.charAt(0).toUpperCase() + propertyName.slice(1),
+                parentId: 'root',
+                propertyName,
+                relationshipType: rel.type === 'hasMany' ? 'array' : 'object',
+                columns: rel.columns || {}
+            });
+        }
+    }
+    return result;
+}
+/**
+ * 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
+ */
+function processJsonMapping(input) {
+    const format = detectMappingFormat(input);
+    let jsonMapping;
+    let metadata = {};
+    try {
+        switch (format) {
+            case 'model-driven':
+                // Validate model-driven input
+                if (!input.typeInfo || !input.structure) {
+                    throw new Error('Model-driven format requires typeInfo and structure fields');
+                }
+                // Convert model-driven to JsonMapping
+                const modelDrivenInput = {
+                    typeInfo: input.typeInfo,
+                    structure: input.structure
+                };
+                const converted = (0, ModelDrivenJsonMapping_1.convertModelDrivenMapping)(modelDrivenInput);
+                jsonMapping = converted.jsonMapping;
+                // Preserve metadata
+                metadata = {
+                    typeInfo: input.typeInfo,
+                    typeProtection: converted.typeProtection
+                };
+                break;
+            case 'unified':
+                // Validate unified input
+                if (!input.rootEntity) {
+                    throw new Error('Unified format requires rootEntity field');
+                }
+                jsonMapping = convertUnifiedFormat(input);
+                break;
+            case 'legacy':
+                // Validate legacy input
+                if (!input.columns && !input.relationships) {
+                    throw new Error('Legacy format requires at least columns or relationships field');
+                }
+                jsonMapping = convertLegacyFormat(input);
+                break;
+            default:
+                throw new Error(`Unsupported mapping format: ${format}`);
+        }
+        return {
+            format,
+            jsonMapping,
+            originalInput: input,
+            metadata
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to process JSON mapping (format: ${format}): ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Convenience function for direct JsonMapping extraction.
+ *
+ * @param input - Any supported JSON mapping format
+ * @returns JsonMapping ready for use with PostgresJsonQueryBuilder
+ */
+function unifyJsonMapping(input) {
+    return processJsonMapping(input).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
+ */
+function isModelDrivenFormat(input) {
+    return detectMappingFormat(input) === 'model-driven';
+}
+/**
+ * Type guard to check if input uses unified format.
+ *
+ * @param input - Mapping input to check
+ * @returns True if input is unified format
+ */
+function isUnifiedFormat(input) {
+    return detectMappingFormat(input) === 'unified';
+}
+/**
+ * Type guard to check if input uses legacy format.
+ *
+ * @param input - Mapping input to check
+ * @returns True if input is legacy format
+ */
+function isLegacyFormat(input) {
+    return detectMappingFormat(input) === 'legacy';
+}
+/**
+ * Migration helper that suggests upgrading to model-driven format.
+ *
+ * @param input - Current mapping configuration
+ * @returns Suggestions for migration (if applicable)
+ */
+function suggestModelDrivenMigration(input) {
+    const format = detectMappingFormat(input);
+    const suggestions = [];
+    if (format !== 'model-driven') {
+        suggestions.push('Consider migrating to model-driven JSON mapping format');
+        suggestions.push('Benefits: Better type safety, IDE support, and future-proof design');
+        suggestions.push('See: Model-Driven JSON Mapping Guide for migration instructions');
+        if (format === 'unified') {
+            suggestions.push('Your current unified format can be automatically converted');
+        }
+        if (format === 'legacy') {
+            suggestions.push('Legacy format support will be maintained but new features target model-driven format');
+        }
+    }
+    return suggestions;
+}
+//# sourceMappingURL=JsonMappingUnifier.js.map

package/dist/src/transformers/JsonMappingUnifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonMappingUnifier.js","sourceRoot":"","sources":["../../../src/transformers/JsonMappingUnifier.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAkDH,kDAkBC;AAqFD,gDA4DC;AAQD,4CAEC;AAQD,kDAEC;AAQD,0CAEC;AAQD,wCAEC;AAQD,kEAmBC;AArRD,qEAA6F;AAyC7F;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAC,KAA0B;IAC1D,kDAAkD;IAClD,IAAI,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACpC,OAAO,cAAc,CAAC;IAC1B,CAAC;IAED,8CAA8C;IAC9C,IAAI,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACrC,OAAO,SAAS,CAAC;IACrB,CAAC;IAED,8CAA8C;IAC9C,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;QACvC,OAAO,QAAQ,CAAC;IACpB,CAAC;IAED,mBAAmB;IACnB,OAAO,QAAQ,CAAC;AACpB,CAAC;AAED;;;;;GAKG;AACH,SAAS,oBAAoB,CAAC,KAA0B;IACpD,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,MAAM,GAAgB;QACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,MAAM;QAClC,UAAU,EAAE;YACR,EAAE,EAAE,KAAK,CAAC,UAAU,CAAC,EAAE,IAAI,MAAM;YACjC,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC,IAAI,IAAI,MAAM;YACrC,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC,OAAO,IAAI,EAAE;SAC1C;QACD,cAAc,EAAE,EAAE;KACrB,CAAC;IAEF,yBAAyB;IACzB,IAAI,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,EAAE,CAAC;QAC9D,MAAM,CAAC,cAAc,GAAG,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACxD,EAAE,EAAE,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,YAAY,IAAI,QAAQ;YAChD,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,YAAY,IAAI,QAAQ;YACpD,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,UAAU,CAAC,EAAE;YACjD,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,QAAQ;YAC7C,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,IAAI,QAAQ;YACrD,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,EAAE;SAChC,CAAC,CAAC,CAAC;IACR,CAAC;IAED,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,SAAS,mBAAmB,CAAC,KAA0B;IACnD,MAAM,MAAM,GAAgB;QACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,MAAM;QAClC,UAAU,EAAE;YACR,EAAE,EAAE,MAAM;YACV,IAAI,EAAE,KAAK,CAAC,QAAQ,IAAI,MAAM;YAC9B,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;SAC/B;QACD,cAAc,EAAE,EAAE;KACrB,CAAC;IACF,0CAA0C;IAC1C,IAAI,KAAK,CAAC,aAAa,IAAI,OAAO,KAAK,CAAC,aAAa,KAAK,QAAQ,EAAE,CAAC;QACjE,KAAK,MAAM,CAAC,YAAY,EAAE,YAAY,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC;YAC7E,gDAAgD;YAChD,MAAM,GAAG,GAAG,YAAmB,CAAC;YAChC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC;gBACvB,EAAE,EAAE,YAAY;gBAChB,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;gBAClE,QAAQ,EAAE,MAAM;gBAChB,YAAY;gBACZ,gBAAgB,EAAE,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ;gBAC7D,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,EAAE;aAC7B,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,kBAAkB,CAAC,KAA0B;IACzD,MAAM,MAAM,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,WAAwB,CAAC;IAC7B,IAAI,QAAQ,GAAqC,EAAE,CAAC;IACpD,IAAI,CAAC;QACD,QAAQ,MAAM,EAAE,CAAC;YACb,KAAK,cAAc;gBACf,8BAA8B;gBAC9B,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;oBACtC,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;gBAClF,CAAC;gBAED,sCAAsC;gBACtC,MAAM,gBAAgB,GAA2B;oBAC7C,QAAQ,EAAE,KAAK,CAAC,QAAS;oBACzB,SAAS,EAAE,KAAK,CAAC,SAAU;iBAC9B,CAAC;gBAEF,MAAM,SAAS,GAAG,IAAA,kDAAyB,EAAC,gBAAgB,CAAC,CAAC;gBAC9D,WAAW,GAAG,SAAS,CAAC,WAAW,CAAC;gBAEpC,oBAAoB;gBACpB,QAAQ,GAAG;oBACP,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,cAAc,EAAE,SAAS,CAAC,cAAc;iBAC3C,CAAC;gBACF,MAAM;YAEV,KAAK,SAAS;gBACV,yBAAyB;gBACzB,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;oBACpB,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;gBAChE,CAAC;gBAED,WAAW,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;gBAC1C,MAAM;YAEV,KAAK,QAAQ;gBACT,wBAAwB;gBACxB,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;oBACzC,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;gBACtF,CAAC;gBAED,WAAW,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;gBACzC,MAAM;YAEV;gBACI,MAAM,IAAI,KAAK,CAAC,+BAA+B,MAAM,EAAE,CAAC,CAAC;QACjE,CAAC;QAED,OAAO;YACH,MAAM;YACN,WAAW;YACX,aAAa,EAAE,KAAK;YACpB,QAAQ;SACX,CAAC;IAEN,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,2CAA2C,MAAM,MAAM,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACrI,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,SAAgB,gBAAgB,CAAC,KAA0B;IACvD,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAC,KAA0B;IAC1D,OAAO,mBAAmB,CAAC,KAAK,CAAC,KAAK,cAAc,CAAC;AACzD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,eAAe,CAAC,KAA0B;IACtD,OAAO,mBAAmB,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,cAAc,CAAC,KAA0B;IACrD,OAAO,mBAAmB,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,2BAA2B,CAAC,KAA0B;IAClE,MAAM,MAAM,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,WAAW,GAAa,EAAE,CAAC;IAEjC,IAAI,MAAM,KAAK,cAAc,EAAE,CAAC;QAC5B,WAAW,CAAC,IAAI,CAAC,wDAAwD,CAAC,CAAC;QAC3E,WAAW,CAAC,IAAI,CAAC,oEAAoE,CAAC,CAAC;QACvF,WAAW,CAAC,IAAI,CAAC,iEAAiE,CAAC,CAAC;QAEpF,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACvB,WAAW,CAAC,IAAI,CAAC,4DAA4D,CAAC,CAAC;QACnF,CAAC;QAED,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;YACtB,WAAW,CAAC,IAAI,CAAC,sFAAsF,CAAC,CAAC;QAC7G,CAAC;IACL,CAAC;IAED,OAAO,WAAW,CAAC;AACvB,CAAC"}

package/dist/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/src/transformers/ModelDrivenJsonMapping.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * Model-driven JSON mapping structure that mirrors TypeScript model definitions.
+ * This approach provides intuitive, hierarchical mapping that closely resembles the target data structure.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertModelDrivenMapping = convertModelDrivenMapping;
+exports.validateModelDrivenMapping = validateModelDrivenMapping;
+/**
+ * Convert a model-driven JSON mapping to the traditional JsonMapping format.
+ * This enables backward compatibility with existing PostgresJsonQueryBuilder.
+ */
+function convertModelDrivenMapping(modelMapping) {
+    const protectedStringFields = [];
+    let entityIdCounter = 0;
+    // Generate unique entity IDs
+    const generateEntityId = () => `entity_${++entityIdCounter}`;
+    // Helper function to process structure fields and extract entities
+    const processStructure = (structure, parentId = null) => {
+        const columns = {};
+        const nestedEntities = [];
+        for (const [fieldName, config] of Object.entries(structure)) {
+            if (typeof config === 'string') {
+                // Simple field mapping: "fieldName": "column_name"
+                columns[fieldName] = config;
+            }
+            else if ('column' in config && typeof config.column === 'string' && !('type' in config && (config.type === 'object' || config.type === 'array'))) {
+                // Enhanced field mapping: "fieldName": { "column": "column_name", "type": "string" }
+                const fieldConfig = config;
+                if (typeof fieldConfig === 'object' && 'column' in fieldConfig) {
+                    columns[fieldName] = fieldConfig.column;
+                    if (fieldConfig.type === 'string') {
+                        protectedStringFields.push(fieldConfig.column);
+                    }
+                }
+            }
+            else if ('from' in config && typeof config.from === 'string' && !('type' in config && (config.type === 'object' || config.type === 'array'))) {
+                // Legacy field mapping: "fieldName": { "from": "column_name", "type": "string" }
+                const fieldConfig = config;
+                if (typeof fieldConfig === 'object' && 'from' in fieldConfig) {
+                    columns[fieldName] = fieldConfig.from;
+                    if (fieldConfig.type === 'string') {
+                        protectedStringFields.push(fieldConfig.from);
+                    }
+                }
+            }
+            else if ('type' in config && (config.type === 'object' || config.type === 'array')) {
+                // Nested structure: object or array
+                const nestedStructure = config;
+                const entityId = generateEntityId();
+                const processedNested = processStructure(nestedStructure.structure, entityId);
+                nestedEntities.push({
+                    id: entityId,
+                    name: fieldName.charAt(0).toUpperCase() + fieldName.slice(1), // Capitalize first letter
+                    parentId: parentId || 'root',
+                    propertyName: fieldName,
+                    relationshipType: nestedStructure.type,
+                    columns: processedNested.columns
+                });
+                // Add nested entities from deeper levels
+                nestedEntities.push(...processedNested.nestedEntities.map(entity => ({
+                    ...entity,
+                    parentId: entity.parentId === 'root' ? entityId : entity.parentId
+                })));
+            }
+        }
+        return { columns, nestedEntities };
+    };
+    // Process the root structure
+    const processed = processStructure(modelMapping.structure); // Build the traditional JsonMapping
+    const jsonMapping = {
+        rootName: 'root', // Default root name
+        rootEntity: {
+            id: 'root',
+            name: 'Root',
+            columns: processed.columns
+        },
+        nestedEntities: processed.nestedEntities
+    };
+    // Add typeInfo for backward compatibility
+    jsonMapping.typeInfo = modelMapping.typeInfo;
+    return {
+        jsonMapping,
+        typeProtection: { protectedStringFields }
+    };
+}
+/**
+ * Validate that a model-driven mapping structure is well-formed.
+ */
+function validateModelDrivenMapping(mapping) {
+    const errors = [];
+    // Validate typeInfo
+    if (!mapping.typeInfo) {
+        errors.push('typeInfo is required');
+    }
+    else {
+        if (!mapping.typeInfo.interface) {
+            errors.push('typeInfo.interface is required');
+        }
+        if (!mapping.typeInfo.importPath) {
+            errors.push('typeInfo.importPath is required');
+        }
+    }
+    // Validate structure
+    if (!mapping.structure || typeof mapping.structure !== 'object') {
+        errors.push('structure is required and must be an object');
+    }
+    return errors;
+}
+//# sourceMappingURL=ModelDrivenJsonMapping.js.map