TeaQL Tool

  ██████████ ███████   █████    ██████  ██      
      ██     ██       ██   ██  ██    ██ ██      
      ██     █████    ███████  ██    ██ ██      
      ██     ██       ██   ██  ██ ▄▄ ██ ██      
      ██     ███████  ██   ██   ██████  ███████ 
      ▲
      │
      │
      │
    T:: The Trusted Tool Facade

A unified, stateless, and AI-friendly standard library facade for the TeaQL platform in Rust.

---

🎯 Motivation

When developing business applications, quick automation scripts, or working with AI coding agents, you frequently need essential tools: parsing dates, generating UUIDs, calculating exact monetary values, reading JSON, checking emails, or encrypting data.

In the Rust ecosystem, this normally requires hunting down dozens of different crates (chrono, uuid, rust_decimal, regex, base64, reqwest, zip, etc.), learning each of their unique APIs, and dealing with potential breaking changes.

TeaQL Tool solves this by providing the T:: Facade.

It gathers the most robust, community-standard crates and wraps them in a completely unified, stateless, and highly predictable API. This drastically lowers the cognitive load for developers and makes it incredibly easy for AI agents to generate correct Rust code without needing to constantly learn new third-party library updates.

📦 Installation

Add teaql-tool to your Cargo.toml. You can selectively opt into features depending on the weight of the dependencies you need.

[dependencies]
# For the standard lightweight utilities
teaql-tool = { version = "0.1", features = ["std"] }

# For everything (including network, crypto, images, web scraping, and watchers)
teaql-tool = { version = "0.1", features = ["std", "extra"] }

---

🛠️ Module Overview & Examples

The facade exposes a static struct T, which you can use to immediately access any module. Simply use teaql_tool::T;.

🧰 Core Data & Logic (teaql-tool-std)

• T::id(): Instantly generate uuid(), ulid(), or nanoid().
• T::time(): Ergonomic timezone-aware math and formatting powered by chrono.

  let tomorrow = T::time().add_days(&T::time().now(), 1);

• T::money(): Exact monetary division and math without floating-point errors.
• T::decimal(): Arbitrary precision math.
• T::codec(): Base64, Hex, URL-encoding in one line.

  let encoded = T::codec().base64_encode(b"Hello");

• T::text(): Case conversions (snake, camel, kebab), truncations, and padding.
• T::json(): Parse to/from JSON, apply JSON Patches, and query via JSON Pointers.
• T::regex(): Extract patterns or validate regex without manual compilation.
• T::list() / T::map(): Quick iterators, grouping, sorting, and map inversions.
• T::diff(): Compare text strings to get unified diffs.
• T::unit(): Convert bytes (KB/MB) and durations.
• T::color(): Convert RGB, HEX, and HSL.

🚀 Automation & Scripts (teaql-tool-extra)

The extra feature pulls in heavier dependencies designed to give your scripts superpowers.

• T::cmd(): Execute shell commands easily with built-in timeouts.

  let (stdout, stderr, code) = T::cmd().run_with_timeout("ls -al", 5).unwrap();

• T::server(): Start a static file HTTP server in one line (blocking).

  T::server().serve_dir("./public", 8080).unwrap();

• T::proxy(): Start a transparent reverse proxy.

  T::proxy().start(8081, "http://127.0.0.1:3000").unwrap();

• T::watcher(): Monitor filesystem changes recursively.

  T::watcher().watch("./src", |changed_path| println!("Changed: {}", changed_path)).unwrap();

• T::archive(): One-line Zip creation and extraction.

  T::archive().zip_dir("./src", "backup.zip").unwrap();

• T::html(): Scrape web content using CSS selectors.

  let links = T::html().select_attr(html_str, "a.active", "href").unwrap();

• T::cron(): Run background scheduling with cron expressions.

  T::cron().schedule("0 * * * * *", || println!("Ran every minute!")).unwrap();

• T::kv(): Open an embedded, pure-Rust key-value database (sled).

  let db = T::kv().open("./local.db").unwrap();
  db.insert("key", "value").unwrap();

• T::clipboard(): Read and write cross-platform clipboard content.
• T::pinyin(): Convert Chinese characters to Pinyin effortlessly.

🌍 Business & Integration (teaql-tool-extra)

• T::http(): Fire off GET/POST requests without setting up async clients manually.
• T::crypto(): Symmetrical (aes-gcm), asymmetrical (rsa), and HMAC signatures.
• T::jwt(): Sign and verify JSON Web Tokens.
• T::email(): Construct and send emails over SMTP.
• T::excel() / T::csv(): Parse spreadsheets directly into lists of structures.
• T::image(): Resize, crop, and convert image formats.
• T::barcode() / T::qrcode(): Generate barcodes and QRCodes as PNG or SVG.
• T::template(): Render Tera templates with JSON data.

---

💻 Full Scripting Example

With teaql-tool, you can write incredibly concise utilities. Here is an example of checking a server, saving the status to a local DB, and writing to the clipboard:

use teaql_tool::T;

fn main() {
    // 1. Fetch data from a URL
    let html = T::http().get("https://rust-lang.org").unwrap();
    
    // 2. Extract specific text using CSS selectors
    let titles = T::html().select_text(&html, "title").unwrap();
    let site_title = &titles[0];

    // 3. Save it to a lightweight local database
    let db = T::kv().open("./scraper.db").unwrap();
    db.insert("latest_title", site_title).unwrap();

    // 4. Copy to your OS clipboard
    T::clipboard().write_text(site_title).unwrap();

    println!("Scraped: {}", site_title);
}

📜 License

This project is licensed under the Apache License, Version 2.0.