Rest
A high-performance TypeScript compiler built with Rust and OXC, designed for 100% compatibility with VSCode's build process.
Quick Start
# Build Rest
cargo build --release --package=Rest
# Run tests
./Element/Rest/run_tests.sh
# Compile TypeScript files
Target/release/Rest compile \
--input ./src \
--output ./out \
--target es2024 \
--module commonjs
# Enable in VSCode build
Compiler=Rest npm run compile-build
cargo build --release --package=Rest
# Run tests
./Element/Rest/run_tests.sh
# Compile TypeScript files
Target/release/Rest compile \
--input ./src \
--output ./out \
--target es2024 \
--module commonjs
# Enable in VSCode build
Compiler=Rest npm run compile-build
What is Rest?
Rest is one of the five Elements in the CodeEditorLand architecture, responsible for compilation and build tooling. It replaces esbuild's TypeScript loader with a Rust-powered compiler that produces VSCode-compatible output.
Why Rust + OXC?
- Performance: Rust + OXC compiles TypeScript 2-3x faster than esbuild
- Compatibility: OXC is used by VSCode internally, ensuring 1:1 output
- Memory Safety: No garbage collection, deterministic performance
- Modern: Built on OXC 0.48, the latest TypeScript infrastructure
Integration
Rest integrates into the build system through environment variables:
# Set the compiler to Rest
export Compiler=Rest
# Optional: Configure Rest binary path
export REST_BINARY_PATH="path/to/Rest"
# Optional: Enable verbose logging
export REST_VERBOSE=true
# Optional: Enable source maps (when implemented)
export RestSourcemap=true
export Compiler=Rest
# Optional: Configure Rest binary path
export REST_BINARY_PATH="path/to/Rest"
# Optional: Enable verbose logging
export REST_VERBOSE=true
# Optional: Enable source maps (when implemented)
export RestSourcemap=true
When Compiler=Rest is set, Element/Output/Source/ESBuild/RestPlugin.ts intercepts TypeScript files and delegates compilation to the Rest binary instead of using esbuild's built-in TypeScript loader.
Features
- Full TypeScript 5.x support
- Decorator handling with
emitDecoratorMetadata -
useDefineForClassFieldscontrol (VSCode: false) - Source map generation (planned)
- Parallel compilation (
--Parallelflag) - Directory-based compilation
- Comprehensive error reporting
- Compilation metrics tracking
CLI Usage
Rest compile [OPTIONS]
Required:
--input, -i <PATH> Input directory containing TypeScript files
--output, -o <PATH> Output directory for compiled JavaScript
Optional:
--target <ES2024> ECMAScript target (default: es2024)
--module <commonjs> Module system: commonjs, esmodule (default: commonjs)
--source-maps Generate source maps (not yet implemented)
--Parallel Enable parallel compilation (default: false)
--use-define-for-class-fields
Use defineForClassFields semantic (default: false)
--help, -h Show help
--version, -V Show version
Required:
--input, -i <PATH> Input directory containing TypeScript files
--output, -o <PATH> Output directory for compiled JavaScript
Optional:
--target <ES2024> ECMAScript target (default: es2024)
--module <commonjs> Module system: commonjs, esmodule (default: commonjs)
--source-maps Generate source maps (not yet implemented)
--Parallel Enable parallel compilation (default: false)
--use-define-for-class-fields
Use defineForClassFields semantic (default: false)
--help, -h Show help
--version, -V Show version
Configuration
Rest supports two main configuration presets:
Simple (Single-File)
use Rest::Struct::CompilerConfig;
let config = CompilerConfig::simple();
// - Target: es2024
// - Module: commonjs
// - Private fields: not converted
// - NLS: disabled
// - Workers: disabled
let config = CompilerConfig::simple();
// - Target: es2024
// - Module: commonjs
// - Private fields: not converted
// - NLS: disabled
// - Workers: disabled
VSCode (Full Pipeline)
let config = CompilerConfig::vscode();
// - Target: es2024
// - Module: esmodule
// - Private fields: converted to __
// - NLS: enabled (localization processing)
// - Workers: enabled
// - Bundling: enabled
// - Target: es2024
// - Module: esmodule
// - Private fields: converted to __
// - NLS: enabled (localization processing)
// - Workers: enabled
// - Bundling: enabled
API Reference
Rust API
use Rest::{Compiler, Struct::CompilerConfig};
// Create compiler with configuration
let config = CompilerConfig::vscode();
let compiler = Compiler::new(config);
// Compile a single file (output goes to same directory with .js extension)
let result = compiler.compile_file(
"path/to/file.ts",
source_code_string
);
// Compile to specific output path
use std::path::Path;
let output_path = Path::new("path/to/output.js");
let result = compiler.compile_file_to(
"input.ts",
source_code_string,
&output_path,
false // use_define_for_class_fields
);
// Check metrics
let metrics = compiler.outlook.lock().unwrap();
println!("Compiled {} files in {:?}",
metrics.count, metrics.elapsed);
// Create compiler with configuration
let config = CompilerConfig::vscode();
let compiler = Compiler::new(config);
// Compile a single file (output goes to same directory with .js extension)
let result = compiler.compile_file(
"path/to/file.ts",
source_code_string
);
// Compile to specific output path
use std::path::Path;
let output_path = Path::new("path/to/output.js");
let result = compiler.compile_file_to(
"input.ts",
source_code_string,
&output_path,
false // use_define_for_class_fields
);
// Check metrics
let metrics = compiler.outlook.lock().unwrap();
println!("Compiled {} files in {:?}",
metrics.count, metrics.elapsed);
Testing
Automated Test Suite
Run the comprehensive test suite:
./Element/Rest/run_tests.sh
Tests cover:
- Binary existence and version
- Simple TypeScript compilation
- Class fields and methods
- Decorators with metadata
- Interfaces and types
- Async functions
- Multiple file batches
- VSCode compatibility mode
- ESM output format
- Parallel compilation
- RestPlugin integration
Integration Testing
Compare Rest output with VSCode's build:
./Element/Rest/benchmark_vscode_compatibility.sh
This script:
- Compiles a sample of VSCode source files with Rest
- Compares output byte-for-byte with VSCode's gulp build
- Reports match percentage and any differences
- Measures performance metrics
Project Structure
Element/Rest/
+-- Source/
| +-- Library.rs # Binary entry point
| +-- Fn/ # Functions/compilation logic
| | +-- OXC/ # OXC-based compiler
| | | +-- Compiler.rs # Main compiler orchestration
| | | +-- Parser.rs # OXC parser wrapper
| | | +-- Transformer.rs # AST transformation
| | | +-- Codegen.rs # Code generation
| | | +-- Compile.rs # (placeholder)
| | +-- SWC/ # Legacy SWC implementation (reference)
| | +-- Binary/ # CLI binary structure
| | | +-- Command.rs # CLI argument parsing
| | +-- Build.rs # Build routines
| | +-- ... # Other features (NLS, Worker, Bundle)
| +-- Struct/ # Data structures
| +-- SWC.rs # CompilerConfig (legacy naming)
| +-- CompilerConfig.rs # Advanced config (Phase 3)
+-- tests/
| +-- integration/
| | +-- vscode_compatibility.rs # Integration tests
| +-- unit/
| +-- oxc_compiler.rs # Unit tests for OXC
+-- Target/
| +-- release/Rest # Compiled binary
+-- COMPILER.md # Detailed documentation
+-- VERIFICATION.md # Test results and verification
+-- run_tests.sh # Test runner script
+-- benchmark_vscode_compatibility.sh # Benchmark script
Architecture
+--------------------------------------------------------------+
| Rest Compiler |
+--------------------------------------------------------------+
| |
| Input: TypeScript files (directory) |
| Output: JavaScript files (directory) |
| |
| Pipeline: |
| 1. Parse (OXC Parser) |
| +-> AST with 'static lifetime |
| 2. Transform (OXC Transformer) |
| +-> Strip TypeScript types |
| +-> Handle decorators |
| +-> Apply useDefineForClassFields |
| 3. Codegen (OXC Codegen) |
| +-> Generate JavaScript |
| 4. Write (Filesystem) |
| +-> Output with preserved directory structure |
| |
| Configuration: |
| - CompilerConfig::simple() |
| - CompilerConfig::vscode() |
| |
| Metrics: |
| - Compilation count |
| - Total elapsed time |
| - Error count |
| |
+--------------------------------------------------------------+