# TSByte ⚡

[![Crates.io Version](https://img.shields.io/crates/v/tsbyte.svg?style=flat-square&color=orange)](https://crates.io/crates/tsbyte)
[![Crates.io Downloads](https://img.shields.io/crates/d/tsbyte.svg?style=flat-square&color=blue)](https://crates.io/crates/tsbyte)
[![Build Status](https://img.shields.io/github/actions/workflow/status/samon/tsbyte/rust.yml?branch=main&style=flat-square)](https://github.com/samon/tsbyte/actions)
[![License](https://img.shields.io/crates/l/tsbyte.svg?style=flat-square&color=green)](https://github.com/samon/tsbyte/blob/main/LICENSE)

**The High-Performance Native TypeScript Compiler for the JVM.**  
*Compile TypeScript directly to native JVM bytecode and executable JARs — without Node.js, V8, Kotlin, or Gradle.*

---

## 🚀 What is TSByte?

**TSByte** is a cutting-edge compiler written in Rust that takes standard TypeScript source files and compiles them directly into Java `.class` files and standalone, executable `.jar` archives. 

Traditional TypeScript execution requires a heavy runtime environment like Node.js, Bun, or Deno. TSByte bypasses interpreter runtimes entirely, translating your TypeScript syntax directly into native, optimized JVM bytecode. You keep the standard TypeScript developer experience — `node_modules`, type checking, and modern ES features — while gaining the legendary performance, reliability, and security of the JVM ecosystem.

---

## ⚡ Performance Comparison

| Metric | Node.js (V8) | JVM + Kotlin / Java | TSByte (Compiled TS) |
| :--- | :---: | :---: | :---: |
| **Startup / Cold Start** | Slow (50ms+) | Slow (150ms+) | **Ultra-Fast (3ms - 5ms)** |
| **Memory Footprint** | Large (30MB+) | Large (80MB+) | **Extremely Low (8MB)** |
| **Deployment Package** | `node_modules` (100MB+) | Heavy Fat JAR (50MB+) | **Standalone JAR (< 100KB)** |
| **Runtime Interpreter** | Required (Node/V8) | Required (JRE) | **Native JVM Bytecode** |

---

## 💡 Key Use Cases (Where TSByte Shines)

TSByte is exceptionally well-suited for high-throughput, modern infrastructure where speed, portability, and security are paramount:

*   ⚡ **High-Performance Serverless & Microservices**: Achieve near-instant millisecond cold starts on AWS Lambda, Google Cloud Functions, or Kubernetes.
*   🛠️ **Zero-Dependency CLI Tools**: Compile your TypeScript command-line utilities into a single, highly portable `.jar` file that runs anywhere Java is installed.
*   🔒 **Secure Enterprise Environments**: Run secure TypeScript programs natively inside highly locked-down corporate JVM networks without installing JavaScript runtime engines.
*   📊 **Distributed Data Processing**: Write type-safe map/reduce, stream filters, or ETL pipelines in TypeScript and run them natively on high-performance JVM data engines (like Apache Spark, Flink, or Hadoop).
*   📦 **Embedded Scripting**: Embed compiled TypeScript routines inside Java desktop, backend, or Android systems as precompiled library classes.

---

## 📦 Installation & Quick Start

Get up and running in seconds with `cargo`:

```bash
# Install the TSByte compiler globally
cargo install tsbyte

# Create a new TSByte project template
tsbyte init my-app
cd my-app

# Compile TypeScript directly to an executable JAR and execute it!
tsbyte jar src/main.ts --output app.jar
java -jar app.jar
```

---

## ⚙️ How It Works Under the Hood

```
TypeScript Source  →  TSByte Compiler  →  JVM Bytecode  →  Executable JAR
   (your code)            (Rust)             (.class)         (java -jar)
```

1. **Write standard TypeScript**: Fully compatible with standard ES2020 types and syntax.
2. **AST Parsing**: TSByte parses your source code and builds an optimized Middle Intermediate Representation (MIR) and High Intermediate Representation (HIR) using SWC.
3. **Native Bytecode Generation**: Generates standard Java 8+ `.class` files directly, executing native closures, arrow functions, and class declarations without any middle-step Kotlin or Java transpilation.
4. **Embedded Zero-Dependency Runtime**: Packages everything — including a specialized JVM-backed, precompiled runtime helper package embedded directly in the compiler's binary — into a standard, lightweight, standalone executable JAR.

---

## 🛠️ CLI Reference

### `tsbyte init [dir]`
Scaffold a standard TypeScript workspace preconfigured for JVM target compilations.
```bash
tsbyte init my-app
```
*   Generates a clean workspace: `package.json`, `tsconfig.json`, `src/main.ts`, and gitignore files.
*   Installs dependencies and sets up scripts.

### `tsbyte compile <file>`
Emit only JVM `.class` files to a target build directory.
```bash
tsbyte compile src/main.ts --output ./build --package com.example.app
```
Options:
*   `-o, --output <dir>` — Output directory (default: `./build`)
*   `-p, --package <pkg>` — Target JVM package path (default: `com.tsbyte.app`)

### `tsbyte jar <file>`
Compile TypeScript to a standalone, executable JAR archive.
```bash
tsbyte jar src/main.ts --output ./app.jar --package com.example.app
```
Options:
*   `-o, --output <path>` — Output `.jar` path (default: `./output.jar`)
*   `-p, --package <pkg>` — Target JVM package path (default: `com.tsbyte.app`)

---

## 🎯 Supported Standard Library & APIs

TSByte features a robust, zero-dependency, JVM-native implementation of standard ES built-ins, offering fully compliant reference equality and performance benefits:

| Built-in | Description | Status |
| :--- | :--- | :---: |
| `Map` | Insertion-ordered, custom key/value hash map mapping JS semantics. | ✅ |
| `Set` | Insertion-ordered unique item collection. | ✅ |
| `WeakMap` | Weak-referencing dynamic key-value map backing JVM `WeakHashMap`. | ✅ |
| `WeakSet` | Weak-referencing membership collection. | ✅ |
| `Date` | Epoch-backed UTC millisecond timestamps, parse wrappers, and getters/setters. | ✅ |
| `RegExp` | Dynamic RegExp engine matching captures, matches, indices, and `.exec()` / `.test()`. | ✅ |
| `JSON` | Native high-performance stringifier and parser. | ✅ |
| `fetch` | Native HTTP Client wrapping JDK's high-performance `HttpClient` with full `Response` support! | ✅ |

### Object Identity Semantics
Unlike JVM structural collections, standard `TsObject` instances feature **Reference Equality identity semantics** (`equals` and `hashCode` delegate to standard reference addresses), perfectly adhering to ECMAScript standard behaviors when tracking object instances in collections.

---

## 📂 Project Architecture

```
src/
├── swc_frontend/   # SWC AST parsing — TS source → AST
├── codegen/
│   ├── compiler/
│   │   ├── bytecode_emitter/ # JVM bytecode generation
│   │   ├── ir_builder/       # AST to HIR/MIR converter
│   │   ├── type_checker/     # Static type validation
│   │   ├── module_graph.rs   # Relative imports/exports path resolver
│   │   ├── runtime_gen.rs    # Embedded Java runtime class bundler
│   │   └── runtime_bytes.rs  # Embedded runtime .class bytes
│   ├── jar.rs                # Executable JAR packager
│   └── mod.rs                # CodeGenerator driver
├── cli/
│   └── init.rs               # Project scaffolding template
├── error.rs                  # Pretty-printed diagnostics
├── lib.rs                    # Public programmatic compiler library API
└── main.rs                   # CLI entrypoint
```

---

## 🤝 Contributing

We welcome contributions of all kinds! Please read our contributing guide to get started.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## 📄 License

Distributed under the MIT License. See `LICENSE` for more information.
