rawsql-ts 0.11.0-beta → 0.11.2-beta

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

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * Enhanced JSON mapping structure that extends the base JsonMapping interface
+ * with additional metadata and type safety features.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertColumnsToLegacy = convertColumnsToLegacy;
+exports.convertToLegacyJsonMapping = convertToLegacyJsonMapping;
+exports.toLegacyMapping = toLegacyMapping;
+exports.extractTypeProtection = extractTypeProtection;
+/**
+ * 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" }
+ * ```
+ */
+function convertColumnsToLegacy(columns) {
+    const result = {};
+    for (const [key, config] of Object.entries(columns)) {
+        if (typeof config === 'string') {
+            result[key] = config;
+        }
+        else if (config && typeof config === 'object') {
+            if ('column' in config) {
+                result[key] = config.column;
+            }
+            else if ('from' in config) {
+                result[key] = config.from;
+            }
+            else {
+                result[key] = key; // fallback
+            }
+        }
+        else {
+            result[key] = key; // fallback
+        }
+    }
+    return result;
+}
+/**
+ * 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
+ */
+function convertToLegacyJsonMapping(input) {
+    if (!input) {
+        throw new Error('Input mapping is required');
+    }
+    // If it's already in legacy format, return as-is
+    if (input.rootName && input.rootEntity &&
+        typeof input.rootEntity.columns === 'object' &&
+        !input.typeInfo && !input.typeProtection && !input.metadata) {
+        // Check if columns are already in string format
+        const allColumnsAreStrings = Object.values(input.rootEntity.columns).every(col => typeof col === 'string');
+        if (allColumnsAreStrings) {
+            return input;
+        }
+    }
+    // Enhanced format conversion
+    if (input.rootName && input.rootEntity) {
+        return {
+            rootName: input.rootName,
+            rootEntity: {
+                id: input.rootEntity.id || 'root',
+                name: input.rootEntity.name || input.rootName,
+                columns: convertColumnsToLegacy(input.rootEntity.columns || {})
+            },
+            nestedEntities: (input.nestedEntities || []).map((entity) => ({
+                id: entity.id,
+                name: entity.name,
+                parentId: entity.parentId,
+                propertyName: entity.propertyName,
+                relationshipType: entity.relationshipType,
+                columns: convertColumnsToLegacy(entity.columns || {})
+            })),
+            resultFormat: input.resultFormat,
+            emptyResult: input.emptyResult
+        };
+    }
+    throw new Error('Unsupported mapping format');
+}
+/**
+ * Converts enhanced mapping to legacy format for backward compatibility.
+ */
+function toLegacyMapping(enhanced) {
+    return {
+        rootName: enhanced.rootName,
+        rootEntity: {
+            id: enhanced.rootEntity.id,
+            name: enhanced.rootEntity.name,
+            columns: convertColumnsToLegacy(enhanced.rootEntity.columns)
+        },
+        nestedEntities: enhanced.nestedEntities.map(entity => ({
+            id: entity.id,
+            name: entity.name,
+            parentId: entity.parentId,
+            propertyName: entity.propertyName,
+            relationshipType: entity.relationshipType,
+            columns: convertColumnsToLegacy(entity.columns)
+        })),
+        resultFormat: enhanced.resultFormat,
+        emptyResult: enhanced.emptyResult
+    };
+}
+/**
+ * Extracts type protection configuration from enhanced mapping.
+ */
+function extractTypeProtection(enhanced) {
+    const protectedStringFields = [];
+    const dateFields = [];
+    const numberFields = [];
+    // Use existing type protection if available
+    if (enhanced.typeProtection) {
+        return {
+            protectedStringFields: enhanced.typeProtection.protectedStringFields || [],
+            dateFields: enhanced.typeProtection.dateFields,
+            numberFields: enhanced.typeProtection.numberFields,
+            customTransforms: enhanced.typeProtection.customTransforms
+        };
+    }
+    // Process root entity
+    for (const [key, config] of Object.entries(enhanced.rootEntity.columns)) {
+        if (typeof config === 'object' && config.type) {
+            const columnName = config.column;
+            switch (config.type) {
+                case 'string':
+                    protectedStringFields.push(columnName);
+                    break;
+                case 'date':
+                    dateFields.push(columnName);
+                    break;
+                case 'number':
+                    numberFields.push(columnName);
+                    break;
+            }
+        }
+    }
+    // Process nested entities
+    for (const entity of enhanced.nestedEntities) {
+        for (const [key, config] of Object.entries(entity.columns)) {
+            if (typeof config === 'object' && config.type) {
+                const columnName = config.column;
+                switch (config.type) {
+                    case 'string':
+                        protectedStringFields.push(columnName);
+                        break;
+                    case 'date':
+                        dateFields.push(columnName);
+                        break;
+                    case 'number':
+                        numberFields.push(columnName);
+                        break;
+                }
+            }
+        }
+    }
+    return {
+        protectedStringFields,
+        dateFields: dateFields.length > 0 ? dateFields : undefined,
+        numberFields: numberFields.length > 0 ? numberFields : undefined,
+        customTransforms: undefined
+    };
+}
+//# sourceMappingURL=EnhancedJsonMapping.js.map

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

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

package/dist/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;
+}