parsec_web #

The Web implementation of the parsec plugin, providing high-performance mathematical equation evaluation through WebAssembly compiled from C++.

Note

This package is endorsed, which means you can simply use parsec normally. This package will be automatically included in your app when you target web platforms.

🚀 Features #

⚡ WebAssembly Performance: Native C++ math library compiled to WASM for optimal speed
🔄 Cross-Platform Consistency: Identical results across all Flutter platforms
📱 Offline-First: No server dependencies, completely self-contained
🎯 Type-Safe: Full Dart type safety with dart:js_interop
🧮 Comprehensive: 100+ mathematical, trigonometric, string, and logical functions

📊 Performance Comparison #

Platform	Implementation	Typical Performance	Network Required
Web (WASM)	C++ → WebAssembly	~1-10ms	❌ No
Android	C++ via JNI	~5-20ms	❌ No
Linux	C++ via FFI	~5-20ms	❌ No
Windows	C++ via FFI	~5-20ms	❌ No

🏗️ Architecture #

graph TD
    A[Flutter Web App] --> B[parsec_web Plugin]
    B --> C[dart:js_interop]
    C --> D[JavaScript Wrapper]
    D --> E[WebAssembly Module]
    E --> F[C++ equations-parser]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style E fill:#fff3e0
    style F fill:#e8f5e8

📦 Installation #

Add parsec to your pubspec.yaml:

dependencies:
  parsec: ^0.3.1  # Latest version

Important

Web Setup Required: For web platforms, you need to include the JavaScript wrapper in your web/index.html file:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Your App</title>
</head>
<body>
  <!-- Add this script tag -->
  <script type="module" src="packages/parsec_web/parsec-web/js/equations_parser_wrapper.js"></script>
  
  <!-- Your existing Flutter scripts -->
  <script src="flutter.js" defer></script>
</body>
</html>

🛠️ Development Setup #

Prerequisites #

For local development and WASM generation, you'll need:

Emscripten (for compiling C++ to WebAssembly)
Node.js (for running JavaScript tests)

📋 Installing Emscripten

Ubuntu/Debian

sudo apt-get update
sudo apt-get install emscripten

Manual Installation

git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh

Verify Installation

emcc --version  # Should show Emscripten version

🔨 Generating WebAssembly Files #

If you need to regenerate the WebAssembly module (for local development):

cd parsec_web
dart bin/generate.dart

This command will:

✅ Check for the parsec-web submodule
⚙️ Compile C++ equations-parser (38 source files) to WebAssembly
📦 Generate wasm/equations_parser.js (~635KB)
✅ Verify all required files are present

Tip

You only need to run this if you're modifying the C++ equations-parser library or if the WASM files are missing.

💻 Usage #

The web implementation provides identical API to other platforms:

import 'package:parsec/parsec.dart';

void main() async {
  final parsec = Parsec();
  
  // Basic arithmetic
  final result1 = await parsec.eval('2 + 3 * 4');          // 14
  final result2 = await parsec.eval('sqrt(16) + pow(2,3)'); // 12.0
  
  // Trigonometric functions
  final result3 = await parsec.eval('sin(pi/2)');          // 1.0
  final result4 = await parsec.eval('cos(0) + tan(pi/4)'); // 2.0
  
  // String operations
  final result5 = await parsec.eval('concat("Hello", " World")'); // "Hello World"
  final result6 = await parsec.eval('length("Flutter")');         // 7
  
  // Logical operations
  final result7 = await parsec.eval('5 > 3 ? "yes" : "no"'); // "yes"
  final result8 = await parsec.eval('true and false');       // false
}

🎯 Web-Specific Features #

The web implementation leverages WebAssembly for optimal performance:

// Complex mathematical expressions are evaluated efficiently
final complexResult = await parsec.eval('''
  sum(
    sin(pi/6) * cos(pi/3),
    sqrt(abs(-16)) / 2,
    log10(100) + ln(e)
  )
'''); // Fast WASM execution

🧪 Testing #

Running JavaScript Tests #

Test the WebAssembly module directly:

cd parsec_web/lib/parsec-web
npm install
npm test

Running Flutter Web Tests #

Test the full integration:

cd parsec
flutter test --platform chrome test/parsec_web_integration_test.dart

🔍 Supported Functions #

📚 Complete Function Reference

📐 Mathematical Functions #

abs(-5)              // 5
sqrt(16)             // 4.0
cbrt(27)             // 3.0
pow(2, 3)            // 8.0
exp(1)               // 2.718...
round(3.7)           // 4
round_decimal(3.14159, 2) // 3.14

📊 Trigonometric Functions #

sin(pi/2)            // 1.0
cos(0)               // 1.0  
tan(pi/4)            // 1.0
asin(1)              // pi/2
acos(1)              // 0
atan(1)              // pi/4
sinh(0)              // 0
cosh(0)              // 1
tanh(0)              // 0

📈 Logarithmic Functions #

ln(e)                // 1.0
log(100)             // 2.0 (base 10)
log10(1000)          // 3.0

🔤 String Functions #

concat("A", "B")     // "AB"
length("Hello")      // 5
toupper("hello")     // "HELLO"
tolower("WORLD")     // "world"
left("Hello", 3)     // "Hel"
right("World", 3)    // "rld"
str2number("42")     // 42
string(123)          // "123"

🔢 Aggregation Functions #

min(1, 2, 3)         // 1
max(1, 2, 3)         // 3
sum(1, 2, 3)         // 6
avg(2, 4, 6)         // 4.0

🧮 Logical Operations #

true and false       // false
true or false        // true
5 > 3                // true
"a" == "a"           // true
5 > 3 ? "yes" : "no" // "yes"

🔤 Constants #

pi                   // 3.14159...
e                    // 2.71828...

⚡ Performance Tips #

Best Practices #

// ✅ Good: Batch multiple calculations
final results = await Future.wait([
  parsec.eval('sin(pi/2)'),
  parsec.eval('cos(0)'),
  parsec.eval('tan(pi/4)'),
]);

// ❌ Avoid: Too many individual evaluations in tight loops
for (int i = 0; i < 1000; i++) {
  await parsec.eval('sqrt($i)'); // Consider batching
}

WebAssembly Optimization #

The WebAssembly module is optimized for:

Size: Single file embedding (~635KB)
Speed: Compiled with -O3 optimization
Compatibility: Works in all modern browsers

🐛 Troubleshooting #

❓ Common Issues & Solutions

"parsec-web JavaScript library not found" #

Problem: The JavaScript wrapper is not loaded in your web app.

Solution:

Add the script tag to your web/index.html:

<script type="module" src="packages/parsec_web/parsec-web/js/equations_parser_wrapper.js"></script>

Ensure WebAssembly files are present:
```
cd parsec_web
dart bin/generate.dart
```

WebAssembly fails to load #

Problem: Browser cannot load or execute the WASM module.

Solutions:

✅ Ensure you're using a modern browser with WebAssembly support
✅ Check browser console for detailed error messages
✅ Try hard refresh (Ctrl+Shift+R) to clear cache
✅ Verify the WASM file exists: ls parsec_web/lib/parsec-web/wasm/

Build errors during development #

Problem: Emscripten compilation fails.

Solutions:

✅ Install Emscripten: sudo apt-get install emscripten
✅ Verify installation: emcc --version
✅ Check submodule: git submodule update --init --recursive
✅ Clean rebuild: rm -rf parsec_web/lib/parsec-web/wasm/ && dart bin/generate.dart

🤝 Contributing #

Fork the repository
Create your feature branch: git checkout -b feature/amazing-feature
Generate WASM files: cd parsec_web && dart bin/generate.dart
Test your changes: flutter test --platform chrome
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

📄 License #

This project is licensed under the Apache-2.0 license - see the LICENSE file for details.

parsec - Main plugin package
parsec_platform_interface - Common interface
parsec_android - Android implementation
parsec_linux - Linux implementation
parsec_windows - Windows implementation

📚 Documentation • 🐛 Issues • 💬 Discussions

Made with ❤️ for the Flutter community

parsec_web 0.1.0 parsec_web: ^0.1.0 copied to clipboard

Metadata