reliant-type 1.0.0

package/dist/cjs/core/schema/mode/interfaces/typescript/ConditionalTypes.js

@@ -0,0 +1,681 @@
+'use strict';
+
+/**
+ *  Unified Conditional Types and Operators System
+ *
+ * A robust, maintainable, and extensible TypeScript conditional types system
+ * with improved error handling, better organization, and  type safety.
+ */
+// ============================================================================
+// OPERATOR SYSTEM -  with validation and metadata
+// ============================================================================
+/**
+ * Comprehensive operator definitions with strict typing
+ */
+exports.Operators = void 0;
+(function (Operators) {
+    // Comprehensive operator configuration
+    Operators.OPERATOR_CONFIG = {
+        // Existence operators (highest precedence)
+        "!exists": {
+            precedence: 100,
+            requiresValue: false,
+            typeSupport: ["string", "number", "boolean", "array", "object", "date"],
+            description: "Field does not exist or is undefined",
+            examples: ["name!exists", "user.email!exists"],
+        },
+        exists: {
+            precedence: 99,
+            requiresValue: false,
+            typeSupport: ["string", "number", "boolean", "array", "object", "date"],
+            description: "Field exists and is not undefined",
+            examples: ["name exists", "user.email exists"],
+        },
+        // State operators
+        "!empty": {
+            precedence: 98,
+            requiresValue: false,
+            typeSupport: ["string", "array", "object"],
+            description: "Field is not empty (non-zero length)",
+            examples: ["name!empty", "items!empty"],
+        },
+        empty: {
+            precedence: 97,
+            requiresValue: false,
+            typeSupport: ["string", "array", "object"],
+            description: "Field is empty (zero length)",
+            examples: ["name empty", "items empty"],
+        },
+        "!null": {
+            precedence: 96,
+            requiresValue: false,
+            typeSupport: ["string", "number", "boolean", "array", "object", "date"],
+            description: "Field is not null",
+            examples: ["value!null", "user.id!null"],
+        },
+        null: {
+            precedence: 95,
+            requiresValue: false,
+            typeSupport: ["string", "number", "boolean", "array", "object", "date"],
+            description: "Field is null",
+            examples: ["value null", "user.id null"],
+        },
+        // Inclusion operators
+        "!in": {
+            precedence: 94,
+            requiresValue: true,
+            typeSupport: ["string", "number", "boolean"],
+            description: "Field value is not in the provided list",
+            examples: ["status!in(active,pending)", "priority!in(1,2,3)"],
+        },
+        in: {
+            precedence: 93,
+            requiresValue: true,
+            typeSupport: ["string", "number", "boolean"],
+            description: "Field value is in the provided list",
+            examples: ["status in(active,pending)", "priority in(1,2,3)"],
+        },
+        // Regex operators
+        "!~": {
+            precedence: 92,
+            requiresValue: true,
+            typeSupport: ["string"],
+            description: "Field value does not match the regex pattern",
+            examples: ["email!~^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"],
+        },
+        "~": {
+            precedence: 91,
+            requiresValue: true,
+            typeSupport: ["string"],
+            description: "Field value matches the regex pattern",
+            examples: ["email~^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"],
+        },
+        // String operators
+        "!contains": {
+            precedence: 90,
+            requiresValue: true,
+            typeSupport: ["string"],
+            description: "Field value does not contain the substring",
+            examples: ["name!contains John", "description!contains urgent"],
+        },
+        contains: {
+            precedence: 89,
+            requiresValue: true,
+            typeSupport: ["string"],
+            description: "Field value contains the substring",
+            examples: ["name contains John", "description contains urgent"],
+        },
+        endsWith: {
+            precedence: 88,
+            requiresValue: true,
+            typeSupport: ["string"],
+            description: "Field value ends with the substring",
+            examples: ["filename endsWith .pdf", "email endsWith @company.com"],
+        },
+        startsWith: {
+            precedence: 87,
+            requiresValue: true,
+            typeSupport: ["string"],
+            description: "Field value starts with the substring",
+            examples: ["name startsWith Mr.", "path startsWith /api/"],
+        },
+        // Comparison operators (lowest precedence)
+        "!=": {
+            precedence: 86,
+            requiresValue: true,
+            typeSupport: ["string", "number", "boolean", "date"],
+            description: "Field value is not equal to the provided value",
+            examples: ["status!=active", "count!=0", "isEnabled!=true"],
+        },
+        ">=": {
+            precedence: 85,
+            requiresValue: true,
+            typeSupport: ["number", "date"],
+            description: "Field value is greater than or equal to the provided value",
+            examples: ["age>=18", "score>=80"],
+        },
+        "<=": {
+            precedence: 84,
+            requiresValue: true,
+            typeSupport: ["number", "date"],
+            description: "Field value is less than or equal to the provided value",
+            examples: ["age<=65", "score<=100"],
+        },
+        ">": {
+            precedence: 83,
+            requiresValue: true,
+            typeSupport: ["number", "date"],
+            description: "Field value is greater than the provided value",
+            examples: ["age>18", "score>80"],
+        },
+        "<": {
+            precedence: 82,
+            requiresValue: true,
+            typeSupport: ["number", "date"],
+            description: "Field value is less than the provided value",
+            examples: ["age<65", "score<100"],
+        },
+        "=": {
+            precedence: 81,
+            requiresValue: true,
+            typeSupport: ["string", "number", "boolean", "date"],
+            description: "Field value is equal to the provided value",
+            examples: ["status=active", "count=0", "isEnabled=true"],
+        },
+    };
+    // Utility functions for operator validation
+    function isValidOperator(op) {
+        return op in Operators.OPERATOR_CONFIG;
+    }
+    Operators.isValidOperator = isValidOperator;
+    function getOperatorsByPrecedence() {
+        return Object.entries(Operators.OPERATOR_CONFIG)
+            .sort(([, a], [, b]) => b.precedence - a.precedence)
+            .map(([op]) => op);
+    }
+    Operators.getOperatorsByPrecedence = getOperatorsByPrecedence;
+    function validateOperatorForType(operator, type) {
+        return Operators.OPERATOR_CONFIG[operator].typeSupport.includes(type);
+    }
+    Operators.validateOperatorForType = validateOperatorForType;
+})(exports.Operators || (exports.Operators = {}));
+// ============================================================================
+// RUNTIME UTILITIES - Implementation helpers
+// ============================================================================
+/**
+ * Runtime utilities for working with conditional expressions
+ */
+exports.Runtime = void 0;
+(function (Runtime) {
+    // Runtime condition evaluator
+    function evaluateCondition(fieldValue, operator, conditionValue) {
+        switch (operator) {
+            // Existence operators
+            case "exists":
+                return fieldValue !== undefined && fieldValue !== null;
+            case "!exists":
+                return fieldValue === undefined || fieldValue === null;
+            // State operators
+            case "empty":
+                if (typeof fieldValue === "string")
+                    return fieldValue.length === 0;
+                if (Array.isArray(fieldValue))
+                    return fieldValue.length === 0;
+                if (typeof fieldValue === "object" && fieldValue !== null) {
+                    return Object.keys(fieldValue).length === 0;
+                }
+                return false;
+            case "!empty":
+                if (typeof fieldValue === "string")
+                    return fieldValue.length > 0;
+                if (Array.isArray(fieldValue))
+                    return fieldValue.length > 0;
+                if (typeof fieldValue === "object" && fieldValue !== null) {
+                    return Object.keys(fieldValue).length > 0;
+                }
+                return true;
+            case "null":
+                return fieldValue === null;
+            case "!null":
+                return fieldValue !== null;
+            // Comparison operators
+            case "=":
+                return String(fieldValue) === conditionValue;
+            case "!=":
+                return String(fieldValue) !== conditionValue;
+            case ">":
+                return Number(fieldValue) > Number(conditionValue);
+            case ">=":
+                return Number(fieldValue) >= Number(conditionValue);
+            case "<":
+                return Number(fieldValue) < Number(conditionValue);
+            case "<=":
+                return Number(fieldValue) <= Number(conditionValue);
+            // String operators
+            case "contains":
+                return String(fieldValue).includes(conditionValue);
+            case "!contains":
+                return !String(fieldValue).includes(conditionValue);
+            case "startsWith":
+                return String(fieldValue).startsWith(conditionValue);
+            case "endsWith":
+                return String(fieldValue).endsWith(conditionValue);
+            // Regex operators
+            case "~":
+                try {
+                    return new RegExp(conditionValue).test(String(fieldValue));
+                }
+                catch {
+                    return false;
+                }
+            case "!~":
+                try {
+                    return !new RegExp(conditionValue).test(String(fieldValue));
+                }
+                catch {
+                    return true;
+                }
+            // Inclusion operators
+            case "in":
+                const inValues = conditionValue.split(",").map((v) => v.trim());
+                return inValues.includes(String(fieldValue));
+            case "!in":
+                const notInValues = conditionValue.split(",").map((v) => v.trim());
+                return !notInValues.includes(String(fieldValue));
+            default:
+                return false;
+        }
+    }
+    Runtime.evaluateCondition = evaluateCondition;
+    // Runtime field value extraction with path support
+    function getFieldValue(data, path) {
+        if (!path || typeof data !== "object" || data === null) {
+            return undefined;
+        }
+        const keys = path.split(".");
+        let current = data;
+        for (const key of keys) {
+            if (current === null || current === undefined) {
+                return undefined;
+            }
+            // Handle array indices
+            if (/^\d+$/.test(key)) {
+                const index = parseInt(key, 10);
+                if (Array.isArray(current) && index >= 0 && index < current.length) {
+                    current = current[index];
+                }
+                else {
+                    return undefined;
+                }
+            }
+            else {
+                current = current[key];
+            }
+        }
+        return current;
+    }
+    Runtime.getFieldValue = getFieldValue;
+    // Runtime conditional expression parser
+    function parseCondition(conditionStr) {
+        const trimmed = conditionStr.trim();
+        // Try operators in precedence order
+        for (const operator of exports.Operators.getOperatorsByPrecedence()) {
+            const config = exports.Operators.OPERATOR_CONFIG[operator];
+            if (!config.requiresValue) {
+                // For operators that don't require a value (exists, empty, null)
+                if (trimmed.endsWith(operator)) {
+                    const field = trimmed.slice(0, -operator.length);
+                    return { field, operator, value: "" };
+                }
+            }
+            else {
+                // For operators that require a value
+                const operatorIndex = trimmed.indexOf(operator);
+                if (operatorIndex > 0) {
+                    const field = trimmed.slice(0, operatorIndex);
+                    const value = trimmed.slice(operatorIndex + operator.length);
+                    return { field, operator, value };
+                }
+            }
+        }
+        return null;
+    }
+    Runtime.parseCondition = parseCondition;
+    // Runtime conditional expression evaluator
+    function evaluateConditionalExpression(data, expression) {
+        // Parse different syntax formats
+        let condition, thenValue, elseValue;
+        // syntax: when condition *? then : else
+        let match = expression.match(/when\s+(.+?)\s*\*\?\s*(.+?)\s*:\s*(.+)/);
+        if (match) {
+            [, condition, thenValue, elseValue] = match;
+        }
+        else {
+            // Parentheses syntax: when(condition) then(value) else(value)
+            match = expression.match(/when\((.+?)\)\s*then\((.+?)\)\s*else\((.+?)\)/);
+            if (match) {
+                [, condition, thenValue, elseValue] = match;
+            }
+            else {
+                // Legacy syntax: when:condition:then:else
+                match = expression.match(/when:(.+?):(.+?):(.+)/);
+                if (match) {
+                    [, condition, thenValue, elseValue] = match;
+                }
+                else {
+                    throw new Error(`Invalid conditional expression format: ${expression}`);
+                }
+            }
+        }
+        // Parse the condition
+        const parsedCondition = parseCondition(condition.trim());
+        if (!parsedCondition) {
+            throw new Error(`Could not parse condition: ${condition}`);
+        }
+        // Get field value
+        const fieldValue = getFieldValue(data, parsedCondition.field);
+        // Evaluate condition
+        const conditionResult = evaluateCondition(fieldValue, parsedCondition.operator, parsedCondition.value);
+        // Return appropriate value
+        return conditionResult
+            ? parseValue(thenValue.trim())
+            : parseValue(elseValue.trim());
+    }
+    Runtime.evaluateConditionalExpression = evaluateConditionalExpression;
+    // Parse value with type coercion
+    function parseValue(value) {
+        const trimmed = value.trim();
+        // Handle quoted strings
+        if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+            (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+            return trimmed.slice(1, -1);
+        }
+        // Handle booleans
+        if (trimmed === "true")
+            return true;
+        if (trimmed === "false")
+            return false;
+        // Handle null/undefined
+        if (trimmed === "null")
+            return null;
+        if (trimmed === "undefined")
+            return undefined;
+        // Handle numbers
+        if (/^-?\d+(\.\d+)?$/.test(trimmed)) {
+            return Number(trimmed);
+        }
+        // Handle arrays (simple comma-separated values)
+        if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+            const arrayContent = trimmed.slice(1, -1);
+            if (arrayContent.trim() === "")
+                return [];
+            return arrayContent.split(",").map((item) => parseValue(item.trim()));
+        }
+        // Default to string
+        return trimmed;
+    }
+    // Validation helper
+    function validateConditionSyntax(condition) {
+        const errors = [];
+        const warnings = [];
+        try {
+            const parsed = parseCondition(condition);
+            if (!parsed) {
+                errors.push("Could not parse condition syntax");
+                return { isValid: false, errors, warnings };
+            }
+            // Validate operator
+            if (!exports.Operators.isValidOperator(parsed.operator)) {
+                errors.push(`Unknown operator: ${parsed.operator}`);
+            }
+            // Validate value requirement
+            const config = exports.Operators.OPERATOR_CONFIG[parsed.operator];
+            if (config.requiresValue && !parsed.value) {
+                errors.push(`Operator '${parsed.operator}' requires a value`);
+            }
+            // Check for common mistakes
+            if (parsed.field.includes(" ")) {
+                warnings.push("Field names with spaces may cause issues");
+            }
+            if (parsed.operator === "~" || parsed.operator === "!~") {
+                try {
+                    new RegExp(parsed.value);
+                }
+                catch {
+                    errors.push("Invalid regex pattern");
+                }
+            }
+        }
+        catch (error) {
+            errors.push(`Validation error: ${error instanceof Error ? error.message : "Unknown error"}`);
+        }
+        return {
+            isValid: errors.length === 0,
+            errors,
+            warnings,
+        };
+    }
+    Runtime.validateConditionSyntax = validateConditionSyntax;
+})(exports.Runtime || (exports.Runtime = {}));
+// ============================================================================
+// FACTORY FUNCTIONS - Convenient creation helpers
+// ============================================================================
+/**
+ * Factory functions for creating conditional expressions
+ */
+exports.Factory = void 0;
+(function (Factory) {
+    function createConditionalBuilder() {
+        return {
+            when(field) {
+                return createFieldBuilder(field);
+            },
+        };
+    }
+    Factory.createConditionalBuilder = createConditionalBuilder;
+    function createFieldBuilder(field) {
+        return {
+            equals: (value) => createThenBuilder(field, "=", value),
+            notEquals: (value) => createThenBuilder(field, "!=", value),
+            greaterThan: (value) => createThenBuilder(field, ">", value),
+            greaterEqual: (value) => createThenBuilder(field, ">=", value),
+            lessThan: (value) => createThenBuilder(field, "<", value),
+            lessEqual: (value) => createThenBuilder(field, "<=", value),
+            matches: (pattern) => createThenBuilder(field, "~", pattern),
+            contains: (value) => createThenBuilder(field, "contains", value),
+            startsWith: (value) => createThenBuilder(field, "startsWith", value),
+            endsWith: (value) => createThenBuilder(field, "endsWith", value),
+            in: (...values) => createThenBuilder(field, "in", values.join(",")),
+            notIn: (...values) => createThenBuilder(field, "!in", values.join(",")),
+            exists: () => createThenBuilder(field, "exists", undefined),
+            notExists: () => createThenBuilder(field, "!exists", undefined),
+            empty: () => createThenBuilder(field, "empty", undefined),
+            notEmpty: () => createThenBuilder(field, "!empty", undefined),
+            isNull: () => createThenBuilder(field, "null", undefined),
+            notNull: () => createThenBuilder(field, "!null", undefined),
+        };
+    }
+    function createThenBuilder(field, operator, value) {
+        return {
+            then: (thenValue) => createElseBuilder(field, operator, value, thenValue),
+            thenType: (type) => createElseBuilder(field, operator, value, type),
+        };
+    }
+    function createElseBuilder(field, operator, value, thenType) {
+        return {
+            else: (elseValue) => createConditionalExpression(field, operator, value, thenType, elseValue),
+            elseType: (type) => createConditionalExpression(field, operator, value, thenType, type),
+            elseWhen: (field2) => createFieldBuilder(field2),
+        };
+    }
+    function createConditionalExpression(field, operator, value, thenType, elseType) {
+        const valueStr = value === undefined ? "" : String(value);
+        const condition = `${field}${operator}${valueStr}`;
+        const expression = `when ${condition} *? ${thenType} : ${elseType}`;
+        return {
+            expression,
+            resultType: (thenType || elseType),
+            metadata: {
+                field,
+                operator,
+                value,
+                validation: exports.Runtime.validateConditionSyntax(condition),
+            },
+            toString: () => expression,
+            validate: () => ({
+                isValid: true,
+                errors: [],
+                warnings: [],
+                result: (thenType || elseType),
+            }),
+        };
+    }
+    // Quick creation helpers
+    function when() {
+        return createConditionalBuilder();
+    }
+    Factory.when = when;
+    function condition(conditionStr) {
+        return {
+            then: (thenValue) => ({
+                else: (elseValue) => `when ${conditionStr} *? ${thenValue} : ${elseValue}`,
+                elseType: (elseType) => `when ${conditionStr} *? ${thenValue} : ${elseType}`,
+            }),
+            thenType: (thenType) => ({
+                else: (elseValue) => `when ${conditionStr} *? ${thenType} : ${elseValue}`,
+                elseType: (elseType) => `when ${conditionStr} *? ${thenType} : ${elseType}`,
+            }),
+        };
+    }
+    Factory.condition = condition;
+})(exports.Factory || (exports.Factory = {}));
+// ============================================================================
+// TESTING UTILITIES - For development and debugging
+// ============================================================================
+/**
+ * Testing and debugging utilities
+ */
+exports.Testing = void 0;
+(function (Testing) {
+    function runTest(testCase) {
+        try {
+            const actual = exports.Runtime.evaluateConditionalExpression(testCase.data, testCase.expression);
+            const passed = JSON.stringify(actual) === JSON.stringify(testCase.expected);
+            return {
+                passed,
+                actual,
+                expected: testCase.expected,
+            };
+        }
+        catch (error) {
+            return {
+                passed: false,
+                actual: undefined,
+                expected: testCase.expected,
+                error: error instanceof Error ? error.message : "Unknown error",
+            };
+        }
+    }
+    Testing.runTest = runTest;
+    function runTestSuite(testCases) {
+        const results = testCases.map((testCase) => ({
+            testCase,
+            result: runTest(testCase),
+        }));
+        const passed = results.filter((r) => r.result.passed).length;
+        const failed = results.length - passed;
+        return { passed, failed, results };
+    }
+    Testing.runTestSuite = runTestSuite;
+    // Example test cases
+    Testing.EXAMPLE_TESTS = [
+        {
+            name: "Simple equality",
+            data: { status: "active" },
+            expression: "when status=active *? enabled : disabled",
+            expected: "enabled",
+        },
+        {
+            name: "Numeric comparison",
+            data: { age: 25 },
+            expression: "when age>=18 *? adult : minor",
+            expected: "adult",
+        },
+        {
+            name: "String contains",
+            data: { email: "user@example.com" },
+            expression: "when email contains @ *? valid : invalid",
+            expected: "valid",
+        },
+        {
+            name: "Existence check",
+            data: { name: "John" },
+            expression: "when name exists *? present : missing",
+            expected: "present",
+        },
+        {
+            name: "Array inclusion",
+            data: { role: "admin" },
+            expression: "when role in(admin,moderator) *? authorized : unauthorized",
+            expected: "authorized",
+        },
+    ];
+})(exports.Testing || (exports.Testing = {}));
+// ============================================================================
+// DOCUMENTATION HELPERS - Auto-generated docs
+// ============================================================================
+/**
+ * Documentation generation utilities
+ */
+exports.Documentation = void 0;
+(function (Documentation) {
+    function generateOperatorDocs() {
+        let docs = "# Conditional Operators Reference\n\n";
+        const groupedOps = {
+            "Existence Operators": ["exists", "!exists"],
+            "State Operators": ["empty", "!empty", "null", "!null"],
+            "Inclusion Operators": ["in", "!in"],
+            "String Operators": [
+                "contains",
+                "!contains",
+                "startsWith",
+                "endsWith",
+            ],
+            "Regex Operators": ["~", "!~"],
+            "Comparison Operators": ["=", "!=", ">", ">=", "<", "<="],
+        };
+        Object.entries(groupedOps).forEach(([group, operators]) => {
+            docs += `## ${group}\n\n`;
+            operators.forEach((op) => {
+                const config = exports.Operators.OPERATOR_CONFIG[op];
+                docs += `### \`${op}\`\n`;
+                docs += `${config.description}\n\n`;
+                docs += `**Type Support:** ${config.typeSupport.join(", ")}\n`;
+                docs += `**Requires Value:** ${config.requiresValue ? "Yes" : "No"}\n`;
+                docs += `**Examples:**\n`;
+                config.examples.forEach((example) => {
+                    docs += `- \`${example}\`\n`;
+                });
+                docs += "\n";
+            });
+        });
+        return docs;
+    }
+    Documentation.generateOperatorDocs = generateOperatorDocs;
+    function generateSyntaxDocs() {
+        return `# Conditional Syntax Reference
+
+## Syntax (Recommended)
+\`\`\`
+when <condition> *? <then_value> : <else_value>
+\`\`\`
+
+Example:
+\`\`\`
+when status=active *? enabled : disabled
+\`\`\`
+
+## Parentheses Syntax
+\`\`\`
+when(<condition>) then(<then_value>) else(<else_value>)
+\`\`\`
+
+Example:
+\`\`\`
+when(status=active) then(enabled) else(disabled)
+\`\`\`
+
+## Legacy Syntax
+\`\`\`
+when:<condition>:<then_value>:<else_value>
+\`\`\`
+
+Example:
+\`\`\`
+when:status=active:enabled:disabled
+\`\`\`
+`;
+    }
+    Documentation.generateSyntaxDocs = generateSyntaxDocs;
+})(exports.Documentation || (exports.Documentation = {}));
+//# sourceMappingURL=ConditionalTypes.js.map