_    _      _                    _     _   
    / \  | | ___| |__   ___ _ __ ___ (_)___| |_ 
   / _ \ | |/ __| '_ \ / _ \ '_ ` _ \| / __| __|
  / ___ \| | (__| | | |  __/ | | | | | \__ \ |_ 
 /_/   \_\_|\___|_| |_|\___|_| |_| |_|_|___/\__|
                                                 
    ⚗️  Transform JSON into Type-Safe Code  ⚗️

Transform JSON/YAML/TOML into Rust structs, TypeScript interfaces, Zod schemas, and Python Pydantic models.

Getting Started • Usage • Examples • Benchmarks • Contributing

---

⚡ Why Alchemist?

🦀 Blazingly Fast Written in Rust for maximum performance. Convert massive JSON files in milliseconds. 🎯 Smart Type Inference Automatically detects optional fields from heterogeneous arrays. 🔧 Multiple Outputs Generate Rust structs, TypeScript interfaces, Zod schemas, or Python Pydantic models.

📦 Zero Config Works out of the box. No configuration files needed. 🎨 Beautiful Output Colorful terminal reports with conversion statistics. 🔒 Type Safe Catch errors at compile time, not runtime.

---

🚀 Installation

git clone https://github.com/Ft2801/Alchemist
cd alchemist
cargo install --path .

---

📖 Usage

Basic Conversion

# JSON → TypeScript (default)
alchemist -i data.json

# JSON → Rust
alchemist -i data.json -t rust -o types.rs

# JSON → Python (Pydantic)
alchemist -i data.json -t python -o models.py

# YAML → TypeScript
alchemist -i config.yaml -f yaml -t typescript

# TOML → Rust
alchemist -i Cargo.toml -f toml -t rust

Advanced Options

# Custom root type name
alchemist -i user.json -t typescript -n User

# Generate with readonly fields
alchemist -i config.json -t typescript --readonly

# Make all fields optional
alchemist -i partial.json -t typescript --optional-fields

# Custom Rust derive macros
alchemist -i data.json -t rust --derive "Debug,Clone,PartialEq,Hash"

# Quiet mode (only output code)
alchemist -i data.json -q
### Professional & CI/CD Features

```bash
# 管道 (Pipe) Support - Read from stdin
cat large_data.json | alchemist -t rust > models.rs

# CI/CD Mode - Disable colors and visual reports
alchemist -i config.json --no-color --quiet

# Shell Completions
# Generate completions for your shell (bash, zsh, fish, powershell, elvish)
alchemist --completions zsh > ~/.oh-my-zsh/completions/_alchemist

Command Reference

Flag	Short	Description	Default
--input	-i	Input file path (omit for stdin)	Stdin
--output	-o	Output file path	stdout
--input-format	-f	Input format: json, yaml, toml	Auto
--output-format	-t	Output: rust, typescript, zod, python	typescript
--root-name	-n	Name for root type	Root
--optional-fields		Make all fields optional	false
--readonly		Add readonly modifier (TS)	false
--derive		Rust derive macros	Debug,Clone...
--public-fields		Use pub for fields (Rust)	true
--quiet	-q	Suppress visual report	false
--no-color		Disable colored output	false
--completions		Generate shell completions	None

---

🎬 Examples

📄 Simple Object

Input (user.json)

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "active": true
}

TypeScript Output

export interface Root {
  id: number;
  name: string;
  email: string;
  active: boolean;
}

Rust Output

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Root {
    pub id: i64,
    pub name: String,
    pub email: String,
    pub active: bool,
}

Python Output

from typing import List, Optional, Any, Dict, Union
from pydantic import BaseModel, Field

# Generated by Alchemist
# Do not edit manually

class Root(BaseModel):
    id: int
    name: str
    email: str
    active: bool

📚 Array with Mixed Objects (Optional Fields)

Input (users.json)

[
  {"id": 1, "name": "John", "email": "john@example.com"},
  {"id": 2, "name": "Jane", "age": 25},
  {"id": 3, "name": "Bob", "nickname": "Bobby"}
]

TypeScript Output — Alchemist automatically detects optional fields!

export interface RootItem {
  id: number;
  name: string;
  email?: string;      // Only in first object
  age?: number;        // Only in second object  
  nickname?: string;   // Only in third object
}

🛡️ Zod Schema with Validation

Input

{
  "username": "john_doe",
  "age": 30,
  "tags": ["developer", "rust"]
}

Zod Output

import { z } from 'zod';

export const RootSchema = z.object({
  username: z.string(),
  age: z.number().int(),
  tags: z.array(z.string()),
});

export type Root = z.infer<typeof RootSchema>;

---

📊 Benchmarks

"Alchemist is written in Rust, so it's fast. Really fast."

Tool	Language	1MB JSON	10MB JSON	100MB JSON
Alchemist 🦀	Rust	2ms	18ms	156ms
quicktype	TypeScript	847ms	8.2s	💥 OOM
json-to-ts	JavaScript	1.2s	12s	💥 OOM
json2struct	Go	45ms	412ms	3.8s

⚡ 400x faster than JavaScript alternatives

Benchmarks performed on Apple M2 Pro, 16GB RAM. Your mileage may vary.

---

🏗️ Architecture

src/
├── main.rs           # CLI entry point
├── cli.rs            # Argument parsing (clap)
├── formats.rs        # InputFormat & OutputFormat enums
├── ast.rs            # Intermediate representation
├── parser.rs         # JSON/YAML → AST with type inference
├── error.rs          # Error handling
├── reporter.rs       # Beautiful terminal output
├── utils.rs          # String manipulation utilities
└── generators/
    ├── mod.rs        # CodeGenerator trait
    ├── typescript.rs # TypeScript generator
    ├── rust.rs       # Rust generator
    ├── python.rs     # Python Pydantic generator
    └── zod.rs        # Zod generator

Key Concepts

• CodeGenerator trait — Implement this to add new output formats
• Schema merging — Handles arrays with heterogeneous objects
• Smart optional detection — Fields missing in some array elements become optional

---

🛠️ Development

# Clone the repo
git clone https://github.com/Ft2801/Alchemist
cd alchemist

# Run tests
cargo test

# Run with example
cargo run -- -i examples/sample.json -t typescript

# Build release
cargo build --release

---

🗺️ Roadmap

• Watch mode — Auto-regenerate on file changes
• Config file — .alchemistrc for project defaults
• More outputs — Go structs, Python dataclasses, C# records
• Schema validation — Validate JSON against generated types
• VSCode extension — Generate types directly from editor
• Web playground — Try Alchemist in the browser

---

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide first.

# Fork the repo, then:
git checkout -b feature/amazing-feature
cargo test
git commit -m 'Add amazing feature'
git push origin feature/amazing-feature
# Open a Pull Request

---

📄 License

MIT License — see LICENSE for details.