crator 0.9.1

High-performance Rust toolkit for HTTP/HTTPS requests, JSON processing, and environment management.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

//! # Info Module
//!
//! Provides high-level functions to interact with the Crates.io API.
//!
//! This module handles fetching crate metadata, parsing the response into the 
//! [`CrateInfo`] struct, and formatting numeric data for human readability.
//!
//! It utilizes the internal [`Http`] client for networking and the [`Json`] 
//! parser for dependency-free data extraction.

use crate::{Http, Json};

/// Represents detailed statistics and metadata for a specific crate.
pub struct CrateInfo {
    /// The most recent version number (e.g., "1.0.2").
    pub latest: String,
    /// A formatted string of downloads (e.g., "1.5k" or "2.3M").
    pub downloads: String,
    /// The exact numeric count of total downloads.
    pub total_downloads: u64,
    /// The total number of versions published to crates.io.
    pub versions: u64,
    /// The license identifier (e.g., "MIT" or "Apache-2.0").
    pub license: String,
    /// The date the crate was first created.
    pub created_at: String,
    /// The date of the last metadata update.
    pub updated_at: String,
}

/// Formats large numbers into a human-readable "k" or "M" string.
///
/// # Examples
/// ```
/// use crator::format_number;
/// assert_eq!(format_number(999), "999");
/// assert_eq!(format_number(1500), "1.5k");
/// assert_eq!(format_number(2500000), "2.5M");
/// ```
pub fn format_number(n: u64) -> String {
    if n < 1000 {
        n.to_string()
    } else if n < 1_000_000 {
        format!("{:.1}k", n as f64 / 1000.0)
    } else {
        format!("{:.1}M", n as f64 / 1_000_000.0)
    }
}

/// Fetches crate metadata from the crates.io API.
///
/// # Errors
/// Returns an error if the network request fails, the User-Agent is rejected,
/// or the API returns an invalid JSON response.
///
/// # Example
/// ```no_run
/// use crator::crate_data;
/// 
/// fn main() -> Result<(), Box<dyn std::error::Error>> {
///     let info = crate_data("serde")?;
///     println!("Latest: v{}", info.latest);
///     Ok(())
/// }
/// ```
pub fn crate_data(crate_name: &str) -> Result<CrateInfo, Box<dyn std::error::Error>> {
    let url = format!("https://crates.io/api/v1/crates/{}", crate_name);
    
    let res = Http::get(&url)
        .header("User-Agent", "crator-client/0.1.0".to_string())
        .send("")?;

    // Parse the JSON once
    let root = Json::from_str(res.body());

    // Use the "crate" object from the response
    let metadata = &root["crate"];

    let total_dl = metadata["downloads"].as_f64().unwrap_or(0.0) as u64;

    let license = root["versions"][0]["license"].unwrap_or("Unknown");

    Ok(CrateInfo {
        latest: metadata["max_version"].to_string_raw(),
        downloads: format_number(total_dl),
        total_downloads: total_dl,
        versions: metadata["versions"].len() as u64,
        license: license, 
        created_at: metadata["created_at"].to_string_raw(),
        updated_at: metadata["updated_at"].to_string_raw(),
    })
}