CRATOR

High-performance Rust toolkit for HTTP/HTTPS requests, JSON processing, and environment management.

---

What is Rust Crator?

• A lightweight, high-performance, and synchronous HTTP/HTTPS client for Rust.

• A lightweight, zero-dependency JSON extractor designed for maximum performance and efficiency.

• High-performance, zero-dependency rsj! macro for declarative, JSX-like JSON generation with support for loops and conditionals.

• High-performance functions to fetch and interact with structured Crates.io API metadata.

• Panic-free utilities for safely loading and managing environment variables.

1. crator::Http;

2. crator::Json;

3. crator::rsj;

4. crator::{CrateInfo, crate_data};

5. crator::{get_env, get_env_or};

---

Installation

To include crator in your Rust project, run:

cargo add crator

Or add crator to your Cargo.toml:

[dependencies]
crator = "MAJOR.MINOR.PATCH" # replace with the actual version

---

Http

A lightweight, high-performance, and synchronous HTTP/HTTPS client for Rust.

Overview

Crator::Http provides a simple yet powerful API for executing HTTP requests with minimal dependencies. It features connection pooling, automatic retries, native TLS support, and full method coverage, making it ideal for high-performance network applications.

Key Features

• Connection Pooling: Reuses TCP/TLS streams via a global agent for reduced latency.
• Automatic Retries: Handles transient network failures automatically.
• Security: Uses system-native TLS backends (SChannel, OpenSSL, Secure Transport).
• Full Method Support: Supports all standard HTTP verbs (GET, POST, PUT, DELETE, etc) and WebDAV extensions (MOVE, LOCK, etc.).

---

Usage Examples

GET Request

use crator::Http;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let response = Http::get("https://jsonplaceholder.typicode.com/posts/1").send("")?;
    println!("Status: {}", response.status());
    println!("Body: {}", response.body());
    Ok(())
}

POST Request with JSON Body

use crator::Http;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let json_body = r#"{"title": "foo", "body": "bar", "userId": 1}"#;
    let response = Http::post("https://jsonplaceholder.typicode.com/posts")
        .header("Content-Type", "application/json".to_string())
        .send(json_body)?;
    println!("Response Status: {}", response.status());
    Ok(())
}

Handling Cookies

use crator::Http;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let response = Http::get("https://httpbin.org")
        .cookie("session_id", "12345")
        .cookie("theme", "dark")
        .send("")?;

    for cookie in response.get_cookies() {
        println!("Set-Cookie: {}", cookie);
    }
    Ok(())
}

HTTP Request Example: Fetching Crates.io Metadata

use crator::Http;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Construct the URL exactly as requested
    let crate_name = "crator"; 
    let url = format!("https://crates.io/api/v1/crates/{}", crate_name);

    // Execute the GET request
    let response = Http::get(&url)
        .header("User-Agent", "crator-client/0.1.0".to_string())
        .timeout(10)
        .send("")?;

    // Check status and display the raw JSON body
    if response.status() == 200 {
        println!("Successfully retrieved metadata for: {}", url);
        println!("JSON Response: {}", response.body());
    } else {
        eprintln!("Failed to fetch data. Status: {}", response.status());
    }

    Ok(())
}

Features

• Request Methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, CONNECT, TRACE, COPY, MOVE, MKCOL, PROPFIND, LOCK, UNLOCK.
• Custom Headers & Cookies: Easily add headers and cookies.
• Timeouts & Redirects: Set request timeouts; follow redirects automatically up to 5 times.
• Persistent Connections: Connection reuse via global agent.

Internal Architecture

• Uses a global Agent for connection pooling.
• Supports both HTTP and HTTPS protocols.
• Handles transfer encodings including chunked transfer.
• Retries on common transient network errors.

---

Json

A lightweight, zero-dependency JSON extractor designed for maximum performance and efficiency.

Overview

Crator::Json provides a minimal and fast way to parse, navigate, and extract data from JSON strings in Rust. It features a simple enum-based structure, recursive data traversal, and no external dependencies, making it ideal for performance-critical applications.

Key Features

• Zero dependencies: No external crates required.
• Fast parsing: Custom recursive parser for maximum speed.
• Flexible navigation: Recursive search for keys within JSON structures.
• Type-safe accessors: Retrieve data as strings or numbers.
• Readable output: Pretty-print JSON with indentation.
• Indexing support: Access objects and arrays using [] syntax.

---

Usage Examples

Parsing JSON

use crator::Json;

fn main() {
    let json_str = r#"{"name": "Rust", "features": ["performance", "safety"], "version": 0.8}"#;
    let parsed = Json::from_str(json_str);

    // Accessing object properties
    if let Some(name) = parsed["name"].as_str() {
        println!("Name: {}", name);
    }

    // Accessing array length
    let features = &parsed["features"];
    println!("Number of features: {}", features.len());

    // Finding nested key
    let version = parsed.find("version");
    println!("Version: {}", version.as_f64().unwrap_or(0.0));
}

Pretty Printing JSON

use crator::Json;

let json_str = r#"{"name": "Rust", "features": ["performance", "safety"], "version": 0.8}"#;
let parsed = Json::from_str(json_str);

println!("{}", parsed.pretty_print(0));

Checking for Null Values

use crator::Json;

let json_str = r#"{"name": "Rust", "features": ["performance", "safety"], "version": 0.8}"#;
let parsed = Json::from_str(json_str);

if parsed["unknown"].is_null() {
    println!("Key not found or null");
}

Features

• Recursive search: find() method searches for keys at any depth.
• Type conversion: as_str(), as_f64() for safe type retrieval.
• Flexible navigation: Index objects and arrays via [].
• Pretty print: Human-readable JSON output.
• No dependencies: Zero external crates.

Internal Architecture

• Uses a custom recursive parser to convert JSON strings into a enum-based structure.
• Supports nested objects and arrays.
• Provides efficient traversal without allocations beyond the initial parse.
• Designed for maximum speed and minimal memory footprint.

---

RSJ

High-performance, zero-dependency rsj! macro for declarative, JSX-like JSON generation with support for loops and conditionals.

Overview

Crator::rsj offers a highly efficient and flexible macro-based approach to generate JSON structures declaratively in Rust. Inspired by JSX syntax, it allows developers to craft complex JSON with nested objects, arrays, and dynamic content through intuitive macros. Supporting multiple indentation styles, conditional logic, and pattern-based iteration, RSJ is ideal for building dynamic JSON payloads in performance-critical applications without external dependencies. Its recursive munching logic ensures clean, readable output while maintaining maximum speed and minimal overhead.

Key Features

• Declarative syntax: Use JSX-like macros for intuitive JSON generation.
• Zero dependencies: No external crates required.
• Support for loops: Generate arrays and repeated structures with pattern matching.
• Conditional logic: Include or exclude parts of JSON based on runtime conditions.
• Multiple indentation styles: Minified, 2-space, or 4-space formatting options.
• Nested structures: Easily build complex nested objects and arrays.
• Pattern-based iteration: Iterate over collections with pattern matching.
• Readable output: Generate well-formatted JSON structures.
• Flexible customization: Control indentation and formatting styles easily.
• Type flexibility: Support for raw values, nested objects, arrays, and literals.
• Flexible keys: Support for both identifiers and quoted strings, enabling keys with spaces, hyphens, and special characters.

---

Usage Examples

Declarative JSON Construction with rsj!

use crator::rsj;

fn main() {
    let items = vec!["Rust", "Forge", "Crator"];
    let is_logged_in = true;
    let has_premium = false; // toggle: true/false

    // toggle: lined, tabed, btfy2, btfy4
    let my_json = rsj!(tabed, obj {
        status: "success",
        code: 200,
        // Conditional Object with If-Else
        if is_logged_in => { 
            user: obj { 
                name: "Ahmed", 
                role: "admin" ,
                age: 24
            } 
        } else { 
            guest: obj { status: "anonymous" } 
        },
        // Standard If (will be empty)
        if has_premium => { 
            rewards: arr { "Badge", "Gift" } 
        },
        data: obj {
            version: "2.1.0",
            tags: arr {
                for item in items => { obj { name: {item} } }
            }
        }
    });

    println!("{}", my_json);
}

Product Inventory JSON Construction with rsj!

use crator::rsj;

fn main() {
    let products = vec![
        ("Laptop", 999.99, true),
        ("Mouse", 25.50, false),
        ("Keyboard", 75.00, true),
    ];

    // Example 1: JSON Object root
    let product_obj = rsj!(btfy4, obj {
        store: "CratorTech",
        inventory: arr {
            for (name, price, available) in products.clone() => {
                obj { 
                    item: {name}, 
                    price: {price}, 
                    available: {available} 
                }
            }
        }
    });

    // Example 2: JSON Array root
    let product_arr = rsj!(btfy4, arr {
        for (name, price, available) in products => {
            obj { 
                item: {name}, 
                price: {price}, 
                available: {available} 
            }
        }
    });

    println!("--- OBJECT ROOT ---\n{}\n", product_obj);
    println!("--- ARRAY ROOT ---\n{}", product_arr);
}

Flexible Keys (Spaces & Hyphens)

use crator::rsj;

fn main() {
    let is_active = true;
    let advanced_json = rsj!(btfy2, obj {
        "API Version": "1.0.2",     // Key with spaces
        "x-api-key": "secret-123",  // Key with hyphens
        
        if is_active => { 
            "user-session": obj {   // Quoted key in conditional
                id: 101,
                status: "verified"
            } 
        },
        
        data: obj {                 // Mixing quoted and unquoted
            "Content-Type": "application/json",
            tags: arr { "rust", "json", "crator" }
        }
    });

    println!("--- ADVANCED JSON ---\n{}\n", advanced_json);
}

Features

• Flexible Keys: Support both standard identifiers and quoted strings, allowing keys with spaces, hyphens, and special characters.
• Conditional Inclusion: Use if condition => { ... } to include keys or objects based on runtime conditions.
• Loops & Iteration: Generate arrays dynamically with for item in collection => { ... }.
• Flexible Formatting: Toggle formatting styles with options like btfy2, btfy4, lined, tabed.
• Nested Structures: Build complex nested JSON objects and arrays seamlessly.
• Concise Syntax: Minimalist macro syntax for clear and readable JSON generation.
• Type Handling: Supports string, number, boolean, object, array, and null types seamlessly.
• Custom Formatting: Easily switch between compact and pretty-printed JSON output.
• No External Dependencies: Pure Rust implementation with zero external crates.

Internal Architecture

• Macro-based DSL: Implements a domain-specific language to interpret and generate JSON structures at compile time.
• Flexible Token Parsing: Uses Token Tree (:tt) matching to support both standard identifiers and quoted string literals for keys.
• String Normalization: Employs compile-time stringification and normalization to ensure keys with spaces or hyphens are formatted correctly without double-quoting.
• Conditional Logic: Supports conditional keys and objects through runtime boolean expressions.
• Recursive Processing: Uses internal recursive "muncher" macros to handle deep nesting, looping, and conditional branches.
• Intermediate Representation: Converts macro input into a structured representation before final serialization into JSON text. Dynamic Data Inclusion: Supports seamless injection of variables and expressions using {variable} syntax within both keys and values.
• Performance Optimized: Focused on compile-time parsing and minimal runtime overhead, producing efficient, pre-formatted JSON strings.
• Zero-Dependency: Pure Rust implementation ensuring a tiny footprint and fast compilation.

---

CrateInfo

High-performance functions to fetch and interact with structured Crates.io API metadata.

Overview

CrateInfo provides high-level utilities for retrieving and processing crate metadata from crates.io. It simplifies fetching crate details, parsing JSON responses, and formatting large numeric data into human-readable strings. Built on top of the lightweight Http client and Json parser, it offers dependency-free, fast, and reliable access to crate information.

Key Features

• Efficient Data Fetching: Uses the internal Http client for network requests.
• Dependency-Free JSON Parsing: Leverages the Json enum for minimal overhead.
• Readable Data Formatting: Converts large numbers into compact formats (k, M).
• Structured Metadata: Provides comprehensive crate statistics and details.

---

Usage Examples

Fetching Crate Metadata

use crator::crate_data;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let crate_name = "mathlab";

    let info = crate_data(crate_name)?;

    println!("-----------------------------------");
    println!("Latest:    v{}", info.latest);
    println!("Versions:  {}", info.versions);
    println!("Downloads: {}", info.downloads);
    println!("total_downloads: {}", info.total_downloads);
    println!("License:   {}", info.license);
    println!("Created:   {}", info.created_at);
    println!("Updated:   {}", info.updated_at);
    println!("-----------------------------------");

    Ok(())
}

// -----------------------------------
// Latest:    v1.5.0
// Versions:  55
// Downloads: 56.3k
// total_downloads: 56326
// License:   MIT OR Apache-2.0
// Created:   2021-02-26T19:02:59.116360Z
// Updated:   2025-10-16T20:18:58.196131Z
// -----------------------------------

Formatting Large Numbers

use crator::format_number;

fn main() {
    println!("{}", format_number(950));       // "950"
    println!("{}", format_number(1500));      // "1.5k"
    println!("{}", format_number(2_500_000)); // "2.5M"
}

Features

• Fetches detailed crate info from crates.io
• Parses and extracts specific metadata fields
• Formats large numbers into human-readable strings
• Easy integration with existing Rust projects

Internal Architecture

• Uses the internal Http client for network requests.
• Parses JSON responses with a dependency-free Json enum.
• Handles common JSON structures returned by the crates.io API.
• Formats and presents data in a user-friendly manner.

---

ENV

Panic-free utilities for safely loading and managing environment variables.

Overview

ENV provides safe, straightforward functions to load environment variables from .env files and retrieve them with optional fallbacks or parsing. Designed to be panic-free, it ensures robust environment management suitable for both development and production environments.

Key Features

• Non-panicking environment loading: Safely loads .env files without panics.
• Flexible retrieval: Fetch environment variables with or without defaults.
• Typed parsing: Convert environment variables into desired types.
• Automatic initialization: Internal .env loading for convenience.
• Error transparency: Returns explicit errors for missing or invalid variables.

---

Usage Examples

Initializing Environment Variables

use crator::init_env;

fn main() {
    if let Err(e) = init_env() {
        eprintln!("Failed to load environment variables: {}", e);
    }
}

Fetching a Required Variable

use crator::get_env;

match get_env("API_KEY") {
    Ok(api_key) => println!("API Key: {}", api_key),
    Err(e) => eprintln!("Error: {}", e),
}

Fetching with Default Value

use crator::get_env_or;

let port = get_env_or("PORT", "8080");
println!("Server running on port: {}", port);

Parsing Environment Variables into Types

use crator::get_env_parse;

let port: u16 = get_env_parse("PORT").unwrap_or(8080);
let debug_mode: bool = get_env_parse("DEBUG").unwrap_or(false);

Fetching and Parsing with Default

use crator::get_env_parse_or;

let max_connections = get_env_parse_or("MAX_CONN", 100);

Features

• Load environment variables from .env files safely
• Retrieve variables with optional defaults
• Parse variables into common types (u16, bool, etc.)
• No panics; returns errors explicitly
• Internal .env loading for convenience

Internal Architecture

• Uses dotenvy for loading .env files.
• Wraps environment variable access with error handling.
• Provides parsing into any type that implements FromStr.
• Designed for safe, panic-free operation.

---

Contributing

Contributions are welcome! If you'd like to contribute to Crator, please fork the repository, create a new branch, and submit a pull request. For larger changes, please discuss your ideas via an issue before implementing them.

---

License

Crator is licensed under either of the following licenses:

• MIT License
• Apache License, Version 2.0

See the LICENSE file for more details.