parsejs_null_safety 2.0.4

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, enablin [...]

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

Parameter	Type	Default	Description
text	String	required	JavaScript code to parse
filename	String?	null	Source filename for error reporting
firstLine	int	1	Starting line number (useful for embedded code)
handleNoise	bool	true	Handle hash bangs and HTML comments
annotations	bool	true	Initialize parent references and scopes
parseAsExpression	bool	false	Parse as expression instead of program

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