rawsql-ts/dist/src/transformers/JsonMappingConverter.d.ts

[beta]High-performance SQL parser and AST analyzer written in TypeScript. Provides fast parsing and advanced transformation capabilities.

/**
 * 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;
}