@syncfusion/ej2-react-form-renderer 0.1.1-beta → 0.1.2-beta

package/src/expressions/ExpressionEngine.js

@@ -0,0 +1,503 @@
+import { ExpressionParser } from './ExpressionParser';
+import { DependencyTracker } from './DependencyTracker';
+import { Internationalization } from '@syncfusion/ej2-base';
+/**
+ * ExpressionEngine - Core evaluation engine
+ *
+ * Safely evaluates user-defined expressions against form state
+ * Supports field references, math operations, functions, and conditionals
+ *
+ * @spec Expression_Engine.md
+ */
+export class ExpressionEngine {
+    parser;
+    dependencyTracker;
+    evaluationCache = new Map();
+    compiledFunctions = new Map();
+    constructor() {
+        this.parser = new ExpressionParser();
+        this.dependencyTracker = new DependencyTracker();
+    }
+    /**
+     * Evaluate expression against form values
+     */
+    evaluate(expression, formValues, options = {}) {
+        try {
+            if (!expression || expression.trim() === '') {
+                return null;
+            }
+            const { timeout = 5000, maxDepth = 10, locale = 'en-US', throwOnError = false } = options;
+            // Check cache
+            const cacheKey = this.getCacheKey(expression, formValues);
+            if (this.evaluationCache.has(cacheKey)) {
+                return this.evaluationCache.get(cacheKey);
+            }
+            // Get or compile function
+            let fn = this.compiledFunctions.get(expression);
+            if (!fn) {
+                fn = this.parser.compile(expression, {
+                    timeout,
+                    maxDepth,
+                    locale
+                });
+                this.compiledFunctions.set(expression, fn);
+            }
+            // Execute with context
+            const context = this.buildContext(formValues);
+            const startTime = Date.now();
+            const result = fn(context);
+            // Validate timeout
+            if (Date.now() - startTime > timeout) {
+                const error = new Error(`Expression evaluation exceeded timeout of ${timeout}ms`);
+                if (throwOnError)
+                    throw error;
+                console.warn(error);
+                return null;
+            }
+            // Cache result
+            this.evaluationCache.set(cacheKey, result);
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error('❌ Expression evaluation error:', message, { expression, formValues });
+            if (options.throwOnError) {
+                throw error;
+            }
+            return null;
+        }
+    }
+    /**
+     * Extract field names referenced in expression
+     */
+    extractDependencies(expression) {
+        if (!expression)
+            return [];
+        return this.dependencyTracker.extractFieldReferences(expression);
+    }
+    /**
+     * Build dependency graph for all expressions
+     */
+    buildDependencyGraph(components) {
+        const graph = {};
+        components.forEach(comp => {
+            if (comp.expressionValue) {
+                const deps = this.extractDependencies(comp.expressionValue);
+                graph[comp.name] = deps;
+            }
+        });
+        return graph;
+    }
+    /**
+     * Detect circular dependencies
+     */
+    detectCircularDependencies(graph) {
+        const visited = new Set();
+        const recursionStack = new Set();
+        const cycles = [];
+        const visit = (node, path) => {
+            visited.add(node);
+            recursionStack.add(node);
+            path.push(node);
+            const deps = graph[node] || [];
+            for (const dep of deps) {
+                if (!visited.has(dep)) {
+                    visit(dep, [...path]);
+                }
+                else if (recursionStack.has(dep)) {
+                    const cycleStart = path.indexOf(dep);
+                    cycles.push([...path.slice(cycleStart), dep]);
+                }
+            }
+            recursionStack.delete(node);
+        };
+        for (const node of Object.keys(graph)) {
+            if (!visited.has(node)) {
+                visit(node, []);
+            }
+        }
+        return cycles;
+    }
+    /**
+     * Get topological order for evaluation
+     */
+    getTopologicalOrder(graph) {
+        const visited = new Set();
+        const order = [];
+        const visit = (node) => {
+            if (visited.has(node))
+                return;
+            visited.add(node);
+            const deps = graph[node] || [];
+            for (const dep of deps) {
+                visit(dep);
+            }
+            order.push(node);
+        };
+        for (const node of Object.keys(graph)) {
+            visit(node);
+        }
+        return order;
+    }
+    /**
+     * Clear internal caches
+     */
+    clearCache() {
+        this.evaluationCache.clear();
+        this.compiledFunctions.clear();
+    }
+    // Private helper methods
+    getCacheKey(expression, formValues) {
+        // Simple cache key (in production, use better hashing)
+        return `${expression}:${JSON.stringify(formValues)}`;
+    }
+    buildContext(formValues) {
+        let intl = new Internationalization();
+        let dFormatter = intl.getDateFormat({
+            format: 'MM/dd/yyyy',
+            type: 'date'
+        });
+        return {
+            // Field values
+            ...formValues,
+            // Constants
+            PI: Math.PI,
+            TRUE: true,
+            FALSE: false,
+            NULL: null,
+            UNDEFINED: undefined,
+            Math: Math,
+            // Aggregate Functions
+            SUM: (values) => Array.isArray(values) ? values.reduce((a, b) => Number(a) + Number(b), 0) : 0,
+            AVG: (values) => {
+                if (!Array.isArray(values) || values.length === 0)
+                    return 0;
+                const sum = values.reduce((a, b) => Number(a) + Number(b), 0);
+                return sum / values.length;
+            },
+            MIN: (values) => Array.isArray(values) && values.length > 0 ? Math.min(...values.map(Number)) : 0,
+            MAX: (values) => Array.isArray(values) && values.length > 0 ? Math.max(...values.map(Number)) : 0,
+            COUNT: (values) => Array.isArray(values) ? values.length : 0,
+            // Math Functions
+            ROUND: (value, decimals = 0) => Math.round(value * Math.pow(10, decimals)) / Math.pow(10, decimals),
+            FLOOR: Math.floor,
+            CEIL: Math.ceil,
+            ABS: Math.abs,
+            SQRT: Math.sqrt,
+            // String Functions
+            UPPER: (text) => String(text).toUpperCase(),
+            LOWER: (text) => String(text).toLowerCase(),
+            CONCAT: (...strings) => strings.map(String).join(''),
+            LENGTH: (text) => String(text).length,
+            TRIM: (text) => String(text).trim(),
+            SUBSTRING: (text, start, length) => length !== undefined
+                ? String(text).substr(start, length)
+                : String(text).substr(start),
+            // Date Functions
+            TODAY: () => {
+                const value = dFormatter(new Date());
+                return value;
+            },
+            AGE: (birthDate) => {
+                const birth = typeof birthDate === 'string' ? new Date(birthDate) : birthDate;
+                const today = new Date();
+                let age = today.getFullYear() - birth.getFullYear();
+                const monthDiff = today.getMonth() - birth.getMonth();
+                if (monthDiff < 0 || (monthDiff === 0 && today.getDate() < birth.getDate())) {
+                    age--;
+                }
+                return age;
+            },
+            DATEFORMAT: (date, format) => {
+                const d = typeof date === 'string' ? new Date(date) : date;
+                let formatter = intl.getDateFormat({
+                    format: format,
+                    type: 'date'
+                });
+                // Simple date format implementation
+                return formatter(d);
+            },
+            DATEDIFF: (date1, date2) => {
+                const d1 = typeof date1 === 'string' ? new Date(date1) : date1;
+                const d2 = typeof date2 === 'string' ? new Date(date2) : date2;
+                return Math.floor((d2.getTime() - d1.getTime()) / (1000 * 60 * 60 * 24));
+            },
+            // Add days to a date (for date arithmetic like {date} + 5)
+            ADDDAYS: (date, days) => {
+                const d = typeof date === 'string' ? new Date(date) : new Date(date);
+                d.setDate(d.getDate() + Number(days));
+                return dFormatter(d);
+            },
+            // Add days to a date (for date arithmetic like {date} + 5)
+            SUBDAYS: (date, days) => {
+                const d = typeof date === 'string' ? new Date(date) : new Date(date);
+                d.setDate(d.getDate() - Number(days));
+                return dFormatter(d);
+            }
+        };
+    }
+}
+/**
+ * ExpressionValidator - Validates expressions before runtime
+ *
+ * Checks syntax, validates field references, and detects circular dependencies
+ *
+ * @spec Expression_Engine.md
+ */
+export class ExpressionValidator {
+    supportedFunctions = [
+        'SUM', 'AVG', 'MIN', 'MAX', 'COUNT',
+        'ROUND', 'FLOOR', 'CEIL', 'ABS', 'SQRT',
+        'UPPER', 'LOWER', 'CONCAT', 'LENGTH', 'TRIM', 'SUBSTRING',
+        'TODAY', 'AGE', 'DATEFORMAT', 'DATEDIFF', 'ADDDAYS', 'SUBDAYS'
+    ];
+    keywords = ['PI', 'TRUE', 'FALSE', 'NULL', 'UNDEFINED', 'and', 'or', 'in'];
+    /**
+     * Validate expression against available fields
+     */
+    validate(expression, availableFields) {
+        const errors = [];
+        if (!expression || expression.trim() === '') {
+            return errors; // Empty expression is valid
+        }
+        // Check syntax
+        const syntaxErrors = this.validateSyntax(expression);
+        errors.push(...syntaxErrors);
+        // Check field references
+        const fieldErrors = this.validateFieldReferences(expression, availableFields);
+        errors.push(...fieldErrors);
+        // Check function calls
+        const funcErrors = this.validateFunctionCalls(expression);
+        errors.push(...funcErrors);
+        // Check field operations based on types
+        const opErrors = this.validateFieldOperations(expression, availableFields);
+        errors.push(...opErrors);
+        return errors;
+    }
+    /**
+     * Validate field operations - check for invalid operators on string/date types
+     */
+    validateFieldOperations(expression, availableFields) {
+        const errors = [];
+        // Skip if not field objects with type info
+        if (!Array.isArray(availableFields) || availableFields.length === 0) {
+            return errors;
+        }
+        const firstField = availableFields[0];
+        if (typeof firstField === 'string') {
+            return errors; // No type information available
+        }
+        // Build field map from objects
+        const fieldMap = new Map();
+        availableFields.forEach(field => {
+            if (field && field.name) {
+                fieldMap.set(field.name, field);
+            }
+        });
+        if (fieldMap.size === 0)
+            return errors;
+        // Track reported operator positions to avoid duplicates
+        const reportedOperators = new Set();
+        // Check each field reference for invalid operations
+        const fieldRefPattern = /(\{[^}]+\})/g;
+        let match;
+        // Invalid operators for string fields (allow only + for concatenation)
+        const stringInvalidOps = ['-', '*', '/', '%', '^'];
+        // Operators invalid for date fields (allow + for date arithmetic with numbers)
+        const dateInvalidOps = ['-', '*', '/', '%', '^', '+'];
+        while ((match = fieldRefPattern.exec(expression)) !== null) {
+            const fieldRef = match[0];
+            const fieldName = fieldRef.slice(1, -1); // Remove { }
+            const field = fieldMap.get(fieldName);
+            if (!field)
+                continue;
+            const fieldIndex = match.index;
+            const fieldEndIndex = fieldIndex + fieldRef.length;
+            // Get context around field reference (including spaces)
+            const textBefore = expression.substring(Math.max(0, fieldIndex - 10), fieldIndex);
+            const textAfter = expression.substring(fieldEndIndex, Math.min(expression.length, fieldEndIndex + 10));
+            // Extract the operator if present (skip spaces)
+            const operatorBefore = textBefore.trimEnd().slice(-1);
+            const operatorAfter = textAfter.trimStart().charAt(0);
+            // Calculate actual position of operators in the original expression
+            const operatorBeforePos = fieldIndex - (textBefore.length - textBefore.trimEnd().length) - 1;
+            const operatorAfterPos = fieldEndIndex + (textAfter.length - textAfter.trimStart().length);
+            // For STRING fields (without format)
+            if (field.type === 'string' && !field.format) {
+                if (operatorBefore && stringInvalidOps.includes(operatorBefore)) {
+                    const key = `${operatorBeforePos}:${operatorBefore}`;
+                    if (!reportedOperators.has(key)) {
+                        errors.push({
+                            type: 'InvalidOperation',
+                            message: `Cannot perform '${operatorBefore}' operation on string field '{${fieldName}}'`
+                        });
+                        reportedOperators.add(key);
+                    }
+                }
+                if (operatorAfter && stringInvalidOps.includes(operatorAfter)) {
+                    const key = `${operatorAfterPos}:${operatorAfter}`;
+                    if (!reportedOperators.has(key)) {
+                        errors.push({
+                            type: 'InvalidOperation',
+                            message: `Cannot perform '${operatorAfter}' operation on string field '{${fieldName}}'`
+                        });
+                        reportedOperators.add(key);
+                    }
+                }
+            }
+            // For DATE fields - allow + with numbers, reject other operators
+            if (field.format === 'date' || field.format === 'date-time' || field.format === 'time') {
+                if (operatorBefore && dateInvalidOps.includes(operatorBefore)) {
+                    const key = `${operatorBeforePos}:${operatorBefore}`;
+                    if (!reportedOperators.has(key)) {
+                        errors.push({
+                            type: 'InvalidOperation',
+                            message: `Cannot perform '${operatorBefore}' operation on date field '{${fieldName}}'`
+                        });
+                        reportedOperators.add(key);
+                    }
+                }
+                if (operatorAfter && dateInvalidOps.includes(operatorAfter)) {
+                    const key = `${operatorAfterPos}:${operatorAfter}`;
+                    if (!reportedOperators.has(key)) {
+                        errors.push({
+                            type: 'InvalidOperation',
+                            message: `Cannot perform '${operatorAfter}' operation on date field '{${fieldName}}'`
+                        });
+                        reportedOperators.add(key);
+                    }
+                }
+                // Allow + only when combined with numbers or number fields
+                if (operatorAfter === '+') {
+                    const operandAfter = textAfter.trimStart().substring(1).trim();
+                    const isNumberField = /^\{[^}]+\}/.test(operandAfter) && fieldMap.get(operandAfter.slice(1, -1))?.type === 'number';
+                    const isNumberLiteral = /^\d+/.test(operandAfter);
+                    if (!isNumberField && !isNumberLiteral) {
+                        const key = `${operatorAfterPos}:${operatorAfter}`;
+                        if (!reportedOperators.has(key)) {
+                            errors.push({
+                                type: 'InvalidOperation',
+                                message: `Date field '{${fieldName}}' can only be used with +number or +{numberField}, not '${operatorAfter}${operandAfter.substring(0, 10)}'`
+                            });
+                            reportedOperators.add(key);
+                        }
+                    }
+                }
+                if (operatorBefore === '+') {
+                    const operandBefore = textBefore.trimEnd().substring(0, textBefore.trimEnd().length - 1).trim();
+                    const isNumberField = /\{[^}]+\}$/.test(operandBefore) && fieldMap.get(operandBefore.slice(operandBefore.lastIndexOf('{') + 1, -1))?.type === 'number';
+                    const isNumberLiteral = /\d+$/.test(operandBefore);
+                    if (!isNumberField && !isNumberLiteral) {
+                        const key = `${operatorBeforePos}:${operatorBefore}`;
+                        if (!reportedOperators.has(key)) {
+                            errors.push({
+                                type: 'InvalidOperation',
+                                message: `Date field '{${fieldName}}' can only be used with +number or +{numberField}`
+                            });
+                            reportedOperators.add(key);
+                        }
+                    }
+                }
+            }
+        }
+        return errors;
+    }
+    validateSyntax(expression) {
+        const errors = [];
+        // Check balanced braces
+        const openBraces = (expression.match(/\{/g) || []).length;
+        const closeBraces = (expression.match(/\}/g) || []).length;
+        if (openBraces !== closeBraces) {
+            errors.push({
+                type: 'SyntaxError',
+                message: 'Unbalanced braces in expression'
+            });
+        }
+        // Check balanced parentheses
+        const openParens = (expression.match(/\(/g) || []).length;
+        const closeParens = (expression.match(/\)/g) || []).length;
+        if (openParens !== closeParens) {
+            errors.push({
+                type: 'SyntaxError',
+                message: 'Unbalanced parentheses in expression'
+            });
+        }
+        // Check balanced $ brackets
+        const openDollar = (expression.match(/\$\{/g) || []).length;
+        const closeDollar = (expression.match(/\}/g) || []).length;
+        if (openDollar > closeDollar) {
+            errors.push({
+                type: 'SyntaxError',
+                message: 'Unbalanced ${ } in expression'
+            });
+        }
+        return errors;
+    }
+    validateFieldReferences(expression, availableFields) {
+        const errors = [];
+        // Skip field validation if availableFields is not properly populated
+        // This allows expressions to work at runtime even if we can't validate field names at editor time
+        if (!availableFields || availableFields.length === 0) {
+            return errors;
+        }
+        const fieldRefPattern = /\{([^{}]+)\}/g;
+        let match;
+        // Handle both string[] and AvailableField[] formats
+        let availableFieldsSet;
+        if (typeof availableFields[0] === 'string') {
+            availableFieldsSet = new Set(availableFields);
+        }
+        else {
+            availableFieldsSet = new Set(availableFields.map(f => f.name));
+        }
+        while ((match = fieldRefPattern.exec(expression)) !== null) {
+            const ref = match[1].trim();
+            // Skip if it's a function call
+            if (this.isFunctionCall(ref))
+                continue;
+            // Skip if it's a math expression (contains operators or numbers)
+            // This distinguishes between {fieldName} and ${5 + 3}
+            if (this.isMathExpression(ref))
+                continue;
+            // Extract field name from nested paths (e.g., "customer.name" -> "customer")
+            const fieldName = ref.split(/[.\[\]]/)[0].trim();
+            // Check if field exists
+            if (fieldName && !this.keywords.includes(fieldName.toUpperCase())) {
+                if (!availableFieldsSet.has(fieldName)) {
+                    errors.push({
+                        type: 'UndefinedField',
+                        message: `Field '${fieldName}' is not defined in the form`,
+                        field: fieldName
+                    });
+                }
+            }
+        }
+        return errors;
+    }
+    validateFunctionCalls(expression) {
+        const errors = [];
+        const funcPattern = /(\w+)\s*\(/g;
+        let match;
+        while ((match = funcPattern.exec(expression)) !== null) {
+            const funcName = match[1];
+            // Only validate uppercase functions (user-defined lowercase functions might be allowed)
+            if (funcName === funcName.toUpperCase() && !this.supportedFunctions.includes(funcName)) {
+                errors.push({
+                    type: 'InvalidFunction',
+                    message: `Unknown function: '${funcName}'. Supported functions: ${this.supportedFunctions.join(', ')}`
+                });
+            }
+        }
+        return errors;
+    }
+    isFunctionCall(ref) {
+        return /^\w+\s*\(/.test(ref);
+    }
+    isMathExpression(ref) {
+        // Check if the expression contains math operators, numbers, or other non-field-name patterns
+        // Math expressions like: "5 + 3", "qty * 2", "age > 18", "sum([1,2,3])"
+        // should be skipped, while field references like "fieldName" or "customer.name" should be validated
+        const mathOperatorPattern = /[\+\-\*\/\%\=\<\>\!\&\|\^\~\s\d]/;
+        return mathOperatorPattern.test(ref);
+    }
+}

package/src/expressions/ExpressionParser.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Field type information for validation
+ */
+export interface AvailableField {
+    name: string;
+    type: string;
+    format?: string;
+}
+/**
+ * ExpressionParser - Parse and compile expressions
+ *
+ * Converts string expressions into safe, compiled functions
+ * Supports field references, operators, functions, and conditionals
+ *
+ * @spec Expression_Engine.md
+ */
+export declare class ExpressionParser {
+    private supportedFunctions;
+    private availableFields;
+    /**
+     * Initialize parser with available fields for type validation
+     */
+    setAvailableFields(fields: AvailableField[]): void;
+    private validateFieldOperations;
+    /**
+     * Validate expression syntax
+     */
+    validate(expression: string): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Compile expression to executable function
+     */
+    compile(expression: string, options?: any): Function;
+    private compileMatrixExpressions;
+    private compileBareFunctionCalls;
+    private compileFieldReferences;
+}