mirror of
https://github.com/oxc-project/oxc.git
synced 2026-09-14 19:36:11 +08:00
Copilot
52 lines
1.9 KiB
Markdown
52 lines
1.9 KiB
Markdown
# Oxc NAPI
|
|
|
|
Node.js Native API bindings for oxc tools.
|
|
|
|
## Overview
|
|
|
|
This crate provides Node.js bindings for oxc tools, enabling JavaScript/TypeScript applications to use oxc's high-performance parsing, linting, and transformation capabilities through native Node.js modules.
|
|
|
|
## Key Features
|
|
|
|
- **Native performance**: Direct access to oxc's Rust implementation
|
|
- **UTF-16 compatibility**: Automatic span conversion for JavaScript strings
|
|
- **Error handling**: Proper JavaScript error propagation
|
|
- **Comment preservation**: Maintains comments during processing
|
|
- **Type safety**: TypeScript definitions for all APIs
|
|
|
|
## Architecture
|
|
|
|
### UTF-8 to UTF-16 Conversion
|
|
|
|
JavaScript uses UTF-16 string encoding, while Rust uses UTF-8. This crate handles the conversion:
|
|
|
|
- **Span conversion**: Updates all source positions to UTF-16 offsets
|
|
- **Comment handling**: Preserves comment positions during conversion
|
|
- **Error mapping**: Ensures error positions are correct in JavaScript
|
|
|
|
### Node.js Integration
|
|
|
|
The bindings are designed for:
|
|
|
|
- **npm packages**: Used by `@oxc-project/` npm packages
|
|
- **Build tools**: Integration with Webpack, Vite, and other bundlers
|
|
- **Editor support**: Language server and editor extension features
|
|
- **CLI tools**: Command-line interfaces for Node.js environments
|
|
|
|
### Error Handling
|
|
|
|
Provides JavaScript-friendly error handling:
|
|
|
|
- **OxcError**: Rust errors converted to JavaScript exceptions
|
|
- **Diagnostic integration**: Rich error messages with source context
|
|
- **Stack traces**: Proper error propagation to JavaScript
|
|
|
|
### Performance Considerations
|
|
|
|
- **Zero-copy**: Minimizes data copying between Rust and JavaScript
|
|
- **Efficient conversion**: Optimized UTF-8 to UTF-16 conversion
|
|
- **Memory management**: Proper cleanup of Rust resources
|
|
- **Async support**: Non-blocking operations where appropriate
|
|
|
|
This crate enables the broader JavaScript ecosystem to benefit from oxc's performance while maintaining familiar JavaScript APIs.
|