NAK-569 Add evalRaw() function for platform-consistent JSON output

[Victorcorcos]

Summary

This PR introduces the evalRaw(equation) function to the parsec-web JavaScript wrapper, providing platform-consistent output that returns raw C++ JSON strings. This enhancement enables seamless integration with Flutter web while maintaining full backward compatibility with the existing eval() API.

🎯 Problem Statement

The current parsec-web library converts C++ JSON results to JavaScript types, causing platform inconsistencies between web and native implementations. This creates challenges for Flutter web integration where unified JSON parsing is expected across all platforms.

Before:

• Web: eval("5 > 3") → true (JavaScript boolean)
• Native: Platform channels of parsec_flutter return '{"val": "true", "type": "b"}' (JSON string)

After:

• Web: evalRaw("5 > 3") → '{"val": "true", "type": "b"}' (Raw C++ JSON)
• Native: Same JSON format → Perfect consistency! ✨

🚀 Solution

New evalRaw(equation) Function

/**
 * Evaluate a mathematical equation and return raw C++ JSON result (for platform consistency)
 * @param {string} equation - The mathematical expression to evaluate
 * @returns {string} The evaluated result as raw JSON string from C++ equations-parser
 * @throws {Error} If the equation is invalid or evaluation fails
 */
evalRaw(equation) // Returns: '{"val": "result", "type": "type"}'

Dual API Design

• eval(equation): Existing behavior with JavaScript type conversion (unchanged)
• evalRaw(equation): New raw JSON output for platform consistency

📋 Key Features

Platform Consistency

// Integer results
evalRaw("2 + 3")           // → '{"val": "5", "type": "i"}'

// Float results  
evalRaw("7 / 2")           // → '{"val": "3.5", "type": "f"}'

// Boolean results
evalRaw("5 > 3")           // → '{"val": "true", "type": "b"}'

// String results
evalRaw('concat("A", "B")') // → '{"val": "AB", "type": "s"}'

// Special float values (exact C++ format)
evalRaw("1/0")             // → '{"val": "inf", "type": "f"}'
evalRaw("0/0")             // → '{"val": "-nan", "type": "f"}'
evalRaw("-1/0")            // → '{"val": "-inf", "type": "f"}'

Error Handling

// Invalid syntax throws exceptions (not JSON errors)
evalRaw("2 + )")           // throws Error: "Parse error message"
evalRaw("")                // throws Error: "Equation cannot be empty"

🧪 Testing

Comprehensive Test Suite

• 344 lines of comprehensive tests in tests/evalraw.test.js
• 35 test cases covering all functionality
• 143/143 total tests passing (including existing tests)

Test Categories

• ✅ Basic arithmetic operations with JSON output
• ✅ Special float values (inf, -inf, -nan)
• ✅ Mathematical functions (trigonometric, logarithmic, etc.)
• ✅ Boolean operations and comparisons
• ✅ String functions and manipulations
• ✅ Complex expressions and nested calls
• ✅ Error handling and edge cases
• ✅ Platform consistency verification
• ✅ Comparison with eval() behavior

Enhanced Internal Testing

Added runComprehensiveTestsBoth() method that tests both eval() and evalRaw() functions simultaneously with detailed reporting.

📁 Files Changed

Core Implementation

• js/equations_parser_wrapper.js: Added evalRaw() function and enhanced testing
  • New evalRaw(equation) method (63 lines)
  • New runComprehensiveTestsBoth() method for dual testing
  • Supporting helper methods: _runSingleTestRaw(), _createTestResultRaw(), _evaluateTestResultRaw()

Test Suite

• tests/evalraw.test.js: Comprehensive test suite (344 lines)
  • 35 focused test cases for evalRaw() functionality
  • Platform consistency validation
  • Comparison tests with eval() behavior

🎁 Benefits

For Flutter Web Integration

1. No platform interface changes needed - Use raw C++ JSON directly
2. Perfect consistency - Identical output format across web and native
3. Simplified data flow - No JavaScript type conversion overhead
4. Preserved semantics - C++ special values maintained exactly

For JavaScript Users

1. Backward compatibility - Existing eval() API unchanged
2. Choice of outputs - Use eval() for JavaScript types or evalRaw() for JSON
3. Enhanced debugging - Raw JSON reveals exact C++ behavior
4. Platform portability - Code works identically across environments

🔍 Implementation Details

Clean Architecture

• Minimal code changes to core functionality
• Follows existing patterns and conventions
• Clear separation between eval() and evalRaw() logic
• Comprehensive error handling maintained

Performance Considerations

• evalRaw() is actually faster (no type conversion overhead)
• Identical C++ evaluation engine used
• No additional memory allocations for type conversion

🧭 Future Considerations

This implementation provides the foundation for:

• Flutter web platform consistency
• Potential elimination of complex platform interface normalization
• Enhanced cross-platform parsec library ecosystem
• Simplified maintenance across web and native implementations

📝 Test Plan

Manual Testing Steps

1. Basic Functionality:

   cd parsec_web/lib/parsec-web
   npm test -- --run evalraw.test.js

2. Full Test Suite:

   npm test

3. Interactive Testing:

   import { default: Parsec } from './index.mjs'
   const parsec = new Parsec()
   await parsec.initialize()
   
   // Test both APIs
   console.log(parsec.eval("2 + 3"))    // → 5 (JavaScript number)
   console.log(parsec.evalRaw("2 + 3")) // → '{"val": "5", "type": "i"}' (JSON string)

Verification Checklist

• All existing tests pass (143/143)
• New evalRaw() tests pass (35/35)
• Both eval() and evalRaw() produce correct outputs
• Error handling works correctly
• Platform consistency maintained
• No breaking changes to existing API

---

🔥 Ready for Flutter Web Integration!