@microsoft/terraform-cdk-constructs 0.0.3-pre.6 → 1.0.0

package/lib/core-azure/lib/azapi/schema-mapper/schema-mapper.d.ts

@@ -0,0 +1,215 @@
+/**
+ * SchemaMapper - A JSII-compliant property transformation engine for Azure API schemas
+ *
+ * This class provides comprehensive property transformation and validation capabilities
+ * for mapping between different API schema versions. It handles property renaming,
+ * restructuring, type conversion, and validation with detailed error reporting.
+ *
+ * Key Features:
+ * - JSII-compliant singleton implementation for multi-language support
+ * - Property transformation with nested object and array support
+ * - Comprehensive validation engine with detailed error reporting
+ * - Default value injection for new properties
+ * - Property path tracking for nested validation errors
+ * - Graceful error handling with contextual information
+ *
+ * @packageDocumentation
+ */
+import { ApiSchema, PropertyDefinition, ValidationResult } from "../../version-manager/interfaces/version-interfaces";
+/**
+ * SchemaMapper class for property transformation and validation
+ *
+ * This class provides a comprehensive property transformation engine that enables
+ * mapping between different API schema versions with full validation support.
+ * It implements JSII-compliant patterns for multi-language code generation.
+ *
+ * The SchemaMapper handles:
+ * - Property transformation between schema versions
+ * - Validation against API schema definitions
+ * - Default value injection for new properties
+ * - Nested object and array processing
+ * - Detailed error reporting with property paths
+ *
+ * @example
+ * const schema: ApiSchema = {
+ *   resourceType: 'Microsoft.Resources/resourceGroups',
+ *   version: '2024-11-01',
+ *   properties: {
+ *     name: { dataType: PropertyType.STRING, required: true },
+ *     location: { dataType: PropertyType.STRING, required: true }
+ *   },
+ *   required: ['name', 'location']
+ * };
+ *
+ * const mapper = SchemaMapper.create(schema);
+ * const result = mapper.validateProperties({ name: 'myRG', location: 'eastus' });
+ *
+ * @stability stable
+ */
+export declare class SchemaMapper {
+    /**
+     * Creates a new SchemaMapper instance for the specified schema
+     *
+     * This factory method creates a SchemaMapper configured for a specific API schema.
+     * The schema defines the structure, validation rules, and transformation mappings
+     * that will be used for property operations.
+     *
+     * @param schema - The API schema to use for transformations and validation
+     * @returns A new SchemaMapper instance configured with the provided schema
+     *
+     * @throws Error if the schema is invalid or missing required properties
+     *
+     * @example
+     * const schema: ApiSchema = {
+     *   resourceType: 'Microsoft.Resources/resourceGroups',
+     *   version: '2024-11-01',
+     *   properties: { name: { dataType: PropertyType.STRING, required: true } },
+     *   required: ['name']
+     * };
+     * const mapper = SchemaMapper.create(schema);
+     */
+    static create(schema: ApiSchema): SchemaMapper;
+    private readonly _schema;
+    private readonly _errorContexts;
+    /**
+     * Private constructor to enforce factory pattern
+     *
+     * @param schema - The API schema to use for this mapper instance
+     */
+    private constructor();
+    /**
+     * Transforms properties from source format to target schema format
+     *
+     * This method applies transformation rules to convert properties from one schema
+     * format to another. It handles property renaming, restructuring, type conversion,
+     * and nested object/array transformations based on the target schema definition.
+     *
+     * @param sourceProps - The source properties to transform
+     * @param targetSchema - The target schema to transform properties to
+     * @returns The transformed properties matching the target schema format
+     *
+     * @throws Error if transformation fails due to incompatible types or missing mappings
+     *
+     * @example
+     * const sourceProps = { oldName: 'value', location: 'eastus' };
+     * const targetSchema = {
+     *   transformationRules: { oldName: 'newName' },
+     *   properties: { newName: { dataType: PropertyType.STRING } }
+     * };
+     * const transformed = mapper.transformProperties(sourceProps, targetSchema);
+     * // Result: { newName: 'value', location: 'eastus' }
+     */
+    transformProperties(sourceProps: any, targetSchema: ApiSchema): any;
+    /**
+     * Validates properties against the schema definition
+     *
+     * This method performs comprehensive validation of properties against the
+     * configured schema. It checks required properties, data types, validation rules,
+     * and provides detailed error reporting with property path information.
+     *
+     * @param properties - The properties to validate
+     * @returns Detailed validation results including errors and warnings
+     *
+     * @example
+     * const properties = { name: 'myRG', location: 'eastus', tags: { env: 'dev' } };
+     * const result = mapper.validateProperties(properties);
+     *
+     * if (!result.valid) {
+     *   console.log('Validation errors:', result.errors);
+     *   console.log('Property errors:', result.propertyErrors);
+     * }
+     */
+    validateProperties(properties: any): ValidationResult;
+    /**
+     * Applies default values to properties based on schema definitions
+     *
+     * This method injects default values for properties that are not provided
+     * but have default values defined in the schema. It preserves existing
+     * property values and only adds defaults for missing properties.
+     *
+     * @param properties - The properties to apply defaults to
+     * @returns New properties object with default values applied
+     *
+     * @example
+     * const props = { name: 'myRG' };
+     * const withDefaults = mapper.applyDefaults(props);
+     * // If schema defines location default as 'eastus':
+     * // Result: { name: 'myRG', location: 'eastus' }
+     */
+    applyDefaults(properties: any): any;
+    /**
+     * Maps a single property value using transformation rules
+     *
+     * This method applies transformation logic to a single property value based on
+     * the target property definition. It handles type conversion, value mapping,
+     * and custom transformations.
+     *
+     * @param propertyName - The name of the property being mapped
+     * @param value - The source value to transform
+     * @param targetProperty - The target property definition from the schema
+     * @returns The transformed property value
+     *
+     * @throws Error if the transformation fails or types are incompatible
+     *
+     * @example
+     * const targetProp = { dataType: PropertyType.STRING, required: true };
+     * const mapped = mapper.mapProperty('name', 'myResourceGroup', targetProp);
+     */
+    mapProperty(propertyName: string, value: any, targetProperty: PropertyDefinition): any;
+    /**
+     * Clears the error context array for a new operation
+     */
+    private _clearErrorContexts;
+    /**
+     * Transforms an object using the target schema
+     */
+    private _transformObject;
+    /**
+     * Transforms a single value based on target property definition
+     */
+    private _transformValue;
+    /**
+     * Transforms value to string type
+     */
+    private _transformToString;
+    /**
+     * Transforms value to number type
+     */
+    private _transformToNumber;
+    /**
+     * Transforms value to boolean type
+     */
+    private _transformToBoolean;
+    /**
+     * Transforms value to array type
+     */
+    private _transformToArray;
+    /**
+     * Transforms value to object type
+     */
+    private _transformToObject;
+    /**
+     * Validates required properties
+     */
+    private _validateRequiredProperties;
+    /**
+     * Validates individual properties against their definitions
+     */
+    private _validateIndividualProperties;
+    /**
+     * Validates property type against definition
+     */
+    private _validatePropertyType;
+    /**
+     * Applies validation rules to a property value
+     */
+    private _applyValidationRules;
+    /**
+     * Applies schema-level validation rules
+     */
+    private _applySchemaValidationRules;
+    /**
+     * Applies default values to an object
+     */
+    private _applyDefaultsToObject;
+}