sheeter_engine/

lib.rs

//! Sheeter is a data file conversion library and CLI tool.
//!
//! This crate provides functions to convert between CSV and JSON formats.
//! It is designed to be small, fast, and portable, suitable for use on
//! low-end devices such as Android phones. The core idea is simple: take
//! data in one format, understand its structure, and emit it in another
//! format without unnecessary overhead.
//!
//! # Examples
//!
//! Convert CSV to JSON:
//!
//! ```
//! use sheeter_engine::csv_to_json;
//!
//! let csv = "name,age\nAlice,30\nBob,25";
//! let json = csv_to_json(csv).unwrap();
//! assert_eq!(json, r#"[{"name":"Alice","age":"30"},{"name":"Bob","age":"25"}]"#);
//! ```
//!
//! Convert JSON to CSV:
//!
//! ```
//! use sheeter_engine::json_to_csv;
//!
//! let json = r#"[{"name":"Alice","age":"30"},{"name":"Bob","age":"25"}]"#;
//! let csv = json_to_csv(json).unwrap();
//! assert_eq!(csv, "name,age\nAlice,30\nBob,25\n");
//! ```

use std::io::Cursor;

/// Converts a delimited string into a JSON array of objects.
///
/// This is the shared engine behind `csv_to_json` and `tsv_to_json`. The first
/// line is read as the header row; every subsequent line becomes a JSON object
/// mapping header names to string cell values. Duplicate header names are
/// rejected because they would silently overwrite data.
///
/// # Errors
///
/// Returns an error on malformed input, duplicate headers, or JSON
/// serialization failure.
///
/// # Examples
///
/// ```
/// use sheeter_engine::csv_to_json;
///
/// let csv = "name,age\nAlice,30";
/// assert_eq!(
///     csv_to_json(csv).unwrap(),
///     r#"[{"name":"Alice","age":"30"}]"#
/// );
/// ```
fn delimited_to_json(input: &str, delim: u8) -> Result<String, Box<dyn std::error::Error>> {
    let input = strip_bom(input);
    let mut rdr = csv::ReaderBuilder::new()
        .delimiter(delim)
        .from_reader(Cursor::new(input));
    let headers = rdr.headers()?.clone();
    let mut seen = std::collections::HashSet::new();
    for header in headers.iter() {
        if !seen.insert(header) {
            return Err(format!("duplicate header: {header}").into());
        }
    }
    let mut records = Vec::new();
    for result in rdr.records() {
        let record = result?;
        let mut map = serde_json::Map::new();
        for (header, value) in headers.iter().zip(record.iter()) {
            map.insert(
                header.to_string(),
                serde_json::Value::String(value.to_string()),
            );
        }
        records.push(serde_json::Value::Object(map));
    }
    Ok(serde_json::to_string(&records)?)
}

/// Converts a JSON array of objects into a delimited string.
///
/// This is the shared engine behind `json_to_csv` and `json_to_tsv`. The header
/// row is the union of all keys across all objects, in first-appearance order.
/// Missing keys become empty cells. Strings are written as-is; numbers and
/// booleans use their JSON literal forms; null becomes an empty cell. Nested
/// objects and arrays cannot be represented losslessly in flat output and cause
/// an error.
///
/// # Errors
///
/// Returns an error if the JSON is not an array of objects, contains nested
/// values, or if writing fails.
///
/// # Examples
///
/// ```
/// use sheeter_engine::json_to_csv;
///
/// let json = r#"[{"a":1},{"a":2,"b":3}]"#;
/// assert_eq!(json_to_csv(json).unwrap(), "a,b\n1,\n2,3\n");
/// ```
fn json_to_delimited(input: &str, delim: u8) -> Result<String, Box<dyn std::error::Error>> {
    let values: Vec<serde_json::Value> = serde_json::from_str(input)?;
    if values.is_empty() {
        return Ok(String::new());
    }
    let mut headers: Vec<String> = Vec::new();
    for value in &values {
        let obj = value.as_object().ok_or("JSON array must contain objects")?;
        for key in obj.keys() {
            if !headers.contains(key) {
                headers.push(key.clone());
            }
        }
    }
    let mut wtr = csv::WriterBuilder::new()
        .delimiter(delim)
        .from_writer(vec![]);
    wtr.write_record(&headers)?;
    for value in values {
        let obj = value.as_object().ok_or("JSON array must contain objects")?;
        let mut record: Vec<String> = Vec::with_capacity(headers.len());
        for h in &headers {
            let cell = match obj.get(h) {
                Some(serde_json::Value::String(s)) => s.clone(),
                Some(serde_json::Value::Number(n)) => n.to_string(),
                Some(serde_json::Value::Bool(b)) => b.to_string(),
                Some(serde_json::Value::Null) => String::new(),
                Some(serde_json::Value::Object(_)) | Some(serde_json::Value::Array(_)) => {
                    return Err(format!(
                        "nested value at key {h} cannot be represented in flat output"
                    )
                    .into());
                }
                None => String::new(),
            };
            record.push(cell);
        }
        wtr.write_record(&record)?;
    }
    let data = wtr.into_inner()?;
    Ok(String::from_utf8(data)?)
}

/// Converts a CSV string into a JSON array of objects.
///
/// CSV (Comma-Separated Values) is a simple tabular format. This function reads
/// the first row as the header and each subsequent row as a record, producing a
/// JSON array of objects. All values are emitted as JSON strings.
///
/// # Errors
///
/// Returns an error on malformed CSV, duplicate headers, or JSON failure.
///
/// # Examples
///
/// ```
/// use sheeter_engine::csv_to_json;
///
/// let csv = "name,age\nAlice,30\nBob,25";
/// let json = csv_to_json(csv).unwrap();
/// assert_eq!(json, r#"[{"name":"Alice","age":"30"},{"name":"Bob","age":"25"}]"#);
/// ```
pub fn csv_to_json(csv: &str) -> Result<String, Box<dyn std::error::Error>> {
    delimited_to_json(csv, b',')
}

/// Converts a TSV string into a JSON array of objects.
///
/// TSV (Tab-Separated Values) is the same tabular model as CSV but uses a tab
/// character as the field separator. This is useful for data exported from
/// spreadsheet tools that prefer tabs over commas.
///
/// # Errors
///
/// Returns an error on malformed TSV, duplicate headers, or JSON failure.
///
/// # Examples
///
/// ```
/// use sheeter_engine::tsv_to_json;
///
/// let tsv = "name\tage\nAlice\t30";
/// let json = tsv_to_json(tsv).unwrap();
/// assert_eq!(json, r#"[{"name":"Alice","age":"30"}]"#);
/// ```
pub fn tsv_to_json(tsv: &str) -> Result<String, Box<dyn std::error::Error>> {
    delimited_to_json(tsv, b'\t')
}

/// Converts a JSON array of objects into a CSV string.
///
/// The header row is the union of all keys across all objects. Missing keys
/// become empty cells. Nested objects or arrays cause an error to prevent
/// silent corruption of round-trips.
///
/// # Errors
///
/// Returns an error if the input is not an array of objects, contains nested
/// values, or if writing fails.
///
/// # Examples
///
/// ```
/// use sheeter_engine::json_to_csv;
///
/// let json = r#"[{"name":"Alice","age":"30"},{"name":"Bob","age":"25"}]"#;
/// assert_eq!(json_to_csv(json).unwrap(), "name,age\nAlice,30\nBob,25\n");
/// ```
pub fn json_to_csv(json: &str) -> Result<String, Box<dyn std::error::Error>> {
    json_to_delimited(json, b',')
}

/// Converts a JSON array of objects into a TSV string.
///
/// Same semantics as `json_to_csv`, but fields are separated by a tab
/// character. The output uses `\n` line endings.
///
/// # Errors
///
/// Returns an error if the input is not an array of objects, contains nested
/// values, or if writing fails.
///
/// # Examples
///
/// ```
/// use sheeter_engine::json_to_tsv;
///
/// let json = r#"[{"name":"Alice","age":"30"},{"name":"Bob","age":"25"}]"#;
/// assert_eq!(json_to_tsv(json).unwrap(), "name\tage\nAlice\t30\nBob\t25\n");
/// ```
pub fn json_to_tsv(json: &str) -> Result<String, Box<dyn std::error::Error>> {
    json_to_delimited(json, b'\t')
}

/// Removes the UTF-8 BOM (`\u{feff}`) from the start of a string if present.
///
/// Some tools (notably Excel) prepend a BOM to CSV/TSV exports. Without
/// stripping, the first header name would include the invisible BOM character
/// and any downstream lookup by name would silently fail. This explicit
/// preprocessing guarantees clean headers regardless of parser behavior.
fn strip_bom(input: &str) -> &str {
    input.strip_prefix('\u{feff}').unwrap_or(input)
}

/// Converts a YAML sequence of mappings into a JSON array of objects.
///
/// This function parses YAML with a strict schema to avoid the "Norway problem":
/// `yes`, `no`, `on`, `off`, `y`, `n` are treated as strings under YAML 1.2
/// semantics. Nested sequences or mappings cause an error because they cannot
/// round-trip losslessly through flat CSV/TSV.
///
/// # Errors
///
/// Returns an error if the YAML is not a sequence of mappings, contains nested
/// values, or if JSON serialization fails.
///
/// # Examples
///
/// ```
/// use sheeter_engine::yaml_to_json;
///
/// let yaml = "- name: Alice\n  age: '30'\n- name: Bob\n  age: '25'\n";
/// let json = yaml_to_json(yaml).unwrap();
/// assert_eq!(json, r#"[{"name":"Alice","age":"30"},{"name":"Bob","age":"25"}]"#);
/// ```
pub fn yaml_to_json(yaml: &str) -> Result<String, Box<dyn std::error::Error>> {
    let opts = serde_saphyr::options! {
        strict_booleans: true,
    };
    let values: Vec<serde_json::Value> = serde_saphyr::from_str_with_options(yaml, opts)?;
    for value in &values {
        let obj = value
            .as_object()
            .ok_or("YAML sequence must contain mappings")?;
        for (key, val) in obj {
            if val.is_object() || val.is_array() {
                return Err(format!(
                    "nested YAML value at key {key} cannot be represented in flat output"
                )
                .into());
            }
        }
    }
    Ok(serde_json::to_string(&values)?)
}

/// Converts a JSON array of objects into a YAML sequence of mappings.
///
/// This is the inverse of `yaml_to_json`. The output is a YAML 1.2 document
/// where each object becomes a mapping in a sequence. Key order is preserved.
/// Nested objects or arrays cause an error for the same reason as CSV: they
/// cannot round-trip losslessly through a flat format.
///
/// # Errors
///
/// Returns an error if the JSON is not an array of objects, contains nested
/// values, or if YAML serialization fails.
///
/// # Examples
///
/// ```
/// use sheeter_engine::json_to_yaml;
///
/// let json = r#"[{"name":"Alice","age":"30"}]"#;
/// let yaml = json_to_yaml(json).unwrap();
/// assert!(yaml.contains("name: Alice"));
/// ```
pub fn json_to_yaml(json: &str) -> Result<String, Box<dyn std::error::Error>> {
    let values: Vec<serde_json::Value> = serde_json::from_str(json)?;
    for value in &values {
        let obj = value.as_object().ok_or("JSON array must contain objects")?;
        for (key, val) in obj {
            if val.is_object() || val.is_array() {
                return Err(format!(
                    "nested JSON value at key {key} cannot be represented in flat YAML"
                )
                .into());
            }
        }
    }
    Ok(serde_saphyr::to_string(&values)?)
}

/// Converts CSV to YAML by composing `csv_to_json` and `json_to_yaml`.
///
/// # Examples
///
/// ```
/// use sheeter_engine::csv_to_yaml;
///
/// let csv = "name,age\nAlice,30";
/// let yaml = csv_to_yaml(csv).unwrap();
/// assert!(yaml.contains("name: Alice"));
/// ```
pub fn csv_to_yaml(csv: &str) -> Result<String, Box<dyn std::error::Error>> {
    json_to_yaml(&csv_to_json(csv)?)
}

/// Converts TSV to YAML by composing `tsv_to_json` and `json_to_yaml`.
///
/// # Examples
///
/// ```
/// use sheeter_engine::tsv_to_yaml;
///
/// let tsv = "name\tage\nAlice\t30";
/// let yaml = tsv_to_yaml(tsv).unwrap();
/// assert!(yaml.contains("name: Alice"));
/// ```
pub fn tsv_to_yaml(tsv: &str) -> Result<String, Box<dyn std::error::Error>> {
    json_to_yaml(&tsv_to_json(tsv)?)
}

/// Converts YAML to CSV by composing `yaml_to_json` and `json_to_csv`.
///
/// # Examples
///
/// ```
/// use sheeter_engine::yaml_to_csv;
///
/// let yaml = "- name: Alice\n  age: '30'\n";
/// let csv = yaml_to_csv(yaml).unwrap();
/// assert_eq!(csv, "name,age\nAlice,30\n");
/// ```
pub fn yaml_to_csv(yaml: &str) -> Result<String, Box<dyn std::error::Error>> {
    json_to_csv(&yaml_to_json(yaml)?)
}

/// Converts YAML to TSV by composing `yaml_to_json` and `json_to_tsv`.
///
/// # Examples
///
/// ```
/// use sheeter_engine::yaml_to_tsv;
///
/// let yaml = "- name: Alice\n  age: '30'\n";
/// let tsv = yaml_to_tsv(yaml).unwrap();
/// assert_eq!(tsv, "name\tage\nAlice\t30\n");
/// ```
pub fn yaml_to_tsv(yaml: &str) -> Result<String, Box<dyn std::error::Error>> {
    json_to_tsv(&yaml_to_json(yaml)?)
}

/// Converts CSV to TSV by composing `csv_to_json` and `json_to_tsv`.
///
/// # Examples
///
/// ```
/// use sheeter_engine::csv_to_tsv;
///
/// let csv = "name,age\nAlice,30";
/// let tsv = csv_to_tsv(csv).unwrap();
/// assert_eq!(tsv, "name\tage\nAlice\t30\n");
/// ```
pub fn csv_to_tsv(csv: &str) -> Result<String, Box<dyn std::error::Error>> {
    json_to_tsv(&csv_to_json(csv)?)
}

/// Converts TSV to CSV by composing `tsv_to_json` and `json_to_csv`.
///
/// # Examples
///
/// ```
/// use sheeter_engine::tsv_to_csv;
///
/// let tsv = "name\tage\nAlice\t30";
/// let csv = tsv_to_csv(tsv).unwrap();
/// assert_eq!(csv, "name,age\nAlice,30\n");
/// ```
pub fn tsv_to_csv(tsv: &str) -> Result<String, Box<dyn std::error::Error>> {
    json_to_csv(&tsv_to_json(tsv)?)
}