ParseJS Null Safety #

ParseJS Null Safety is a robust JavaScript parser for Dart with full null safety support. This package provides a complete JavaScript parsing solution that generates Abstract Syntax Trees (ASTs) for JavaScript code, enabling code analysis, transformation, and compilation tools.

✨ Features #

• Full Null Safety: Built for Dart 3.5+ with complete null safety support
• Comprehensive Parsing: Supports modern JavaScript syntax and features
• Efficient AST Generation: Fast parsing with detailed node information
• Configurable Options: Noise handling, annotations, expression parsing
• Well-Tested: Thoroughly tested against real-world JavaScript code
• Lightweight: Minimal dependencies, focused on core functionality
• Production Ready: Stable and reliable for production use

🚀 Use Cases #

Perfect for building:

• JavaScript Tooling: Code analyzers, linters, and formatters
• Code Transformation: AST manipulation and code generation
• Static Analysis: Code quality checks and security analysis
• Compilation Tools: JavaScript to other language transpilers
• IDE Features: Syntax highlighting, code completion, and refactoring
• Documentation Generators: Code structure analysis and documentation

📦 Installation #

Add this to your pubspec.yaml:

dependencies:
  parsejs_null_safety: ^2.0.4

Then run:

dart pub get

💡 Quick Start #

Basic Usage #

import 'package:parsejs_null_safety/parsejs_null_safety.dart';

void main() {
  const code = 'const message = "Hello, World!"; console.log(message);';
  
  // Parse JavaScript code into an AST
  final ast = parsejs(code);
  
  print('Parsed successfully!');
  print('AST has ${ast.body.length} statements');
}

File Parsing #

import 'package:parsejs_null_safety/parsejs_null_safety.dart';
import 'dart:io';

void main() async {
  final file = File('script.js');
  final code = await file.readAsString();
  
  // Parse with filename for better error reporting
  final ast = parsejs(code, filename: 'script.js');
  
  // Process the AST
  print('File parsed successfully');
  print('Filename: ${ast.filename}');
  print('Statements: ${ast.body.length}');
}

Expression Parsing #

import 'package:parsejs_null_safety/parsejs_null_safety.dart';

void main() {
  const expression = 'x * y + z';
  
  // Parse as an expression (not a full program)
  final ast = parsejs(expression, parseAsExpression: true);
  
  print('Expression parsed successfully');
}

🔧 API Reference #

The parsejs function provides comprehensive parsing options:

Function Signature #

Program parsejs(
  String text, {
  String? filename,
  int firstLine = 1,
  bool handleNoise = true,
  bool annotations = true,
  bool parseAsExpression = false,
})

Parameters #

Return Value #

Returns a Program object containing the complete Abstract Syntax Tree with:

• Body: List of statements and declarations
• Filename: Source filename (if provided)
• Detailed Node Information: Position, line numbers, and relationships

🧪 Testing #

Run Unit Tests #

dart test

Run Legacy Tests #

For comprehensive JavaScript compatibility testing:

1. Navigate to test/util directory
2. Run npm install
3. Go to test/ directory and run ./runtest

📚 Examples #

Check out the example/ directory for more detailed usage examples:

• Basic parsing examples
• File handling demonstrations
• AST traversal patterns
• Error handling scenarios

🔗 Related Projects #

• Original ParseJS: https://github.com/asgerf/parsejs.dart
• Ensemble UI: https://ensembleui.com

🤝 Contributing #

We welcome contributions! Please feel free to:

• Report bugs and issues
• Suggest new features
• Submit pull requests
• Improve documentation

📄 License #

This project is licensed under the same license as the original ParseJS project.

Built with ❤️ for the Dart community