adapters 0.0.0

Documentation | API Reference | Quick Start | Contributing

A production-grade, high-performance schema and data transformations library for Rust, designed with a clean, intuitive, and developer-friendly API.

[!NOTE] This Project aims to be production ready, while it is relatively new project you can find some interesting features which may simplify your Rust project structured validations and data transformations.

⭐️ If you love adapters, make sure to give it a star! ⭐️

• Prerequisites
• Supported Platforms
• Installation
  • Method 1: Cargo Add (Recommended)
  • Method 2: Manual Cargo.toml Configuration
• Quick Start
• Usage Examples
  • Basic Declarative Validation
  • Advanced Macro Validations
  • Programmatic Builder Validation
  • Nested Model Validation
  • Field Transformation Pipelines
  • Alias Key Remapping
• Declarative Macro Reference Table
• Performance & Benchmarks
• Building & Testing
• Documentation
  • Online Documentation
  • Generating Local Documentation
• Contributing
• License
• Links

Prerequisites

Before installing Adapters, ensure you have the following:

Supported Platforms

Adapters supports a wide range of platforms and architectures:

Installation

Method 1: Cargo Add (Recommended)

Add Adapters to your cargo project dynamically:

cargo add adapters

Method 2: Manual Cargo.toml Configuration

Add this directly to your Cargo.toml dependencies block:

[dependencies]

adapters = "0.0.0"

Quick Start

use adapters::prelude::*;

#[derive(Schema, Debug)]
struct UserRegistration {
    #[schema(min_length = 3, max_length = 20, alphanumeric)]
    username: String,

    #[schema(email)]
    email: String,

    #[schema(positive)]
    age: u8,
}

fn main() -> Result<(), Error> {
    let raw_payload = r#"{
        "username": "Fiaz2026",
        "email": "contact@example.com",
        "age": 28
    }"#;

    // Direct structural deserialization & validation
    let user = UserRegistration::from_json(raw_payload)?;
    println!("Successfully validated user: {:?}", user);

    Ok(())
}

Usage Examples

Basic Declarative Validation

use adapters::prelude::*;

#[derive(Schema)]
struct SimpleUser {
    name: String,
    #[schema(optional, default = "Guest")]
    role: String,
}

Advanced Macro Validations

use adapters::prelude::*;

#[derive(Schema)]
struct SecureAsset {
    #[schema(non_empty, alphanumeric)]
    serial_code: String,

    #[schema(positive)]
    quantity: i32,

    #[schema(negative)]
    balance_deficit: f64,

    #[schema(non_zero)]
    tracking_id: i64,
}

Programmatic Builder Validation

use adapters::prelude::*;
use adapters::schema::{ObjectSchema, StringSchema, IntegerSchema};
use adapters::SchemaValidator;

let schema = ObjectSchema::new()
    .field("username", StringSchema::new().required().non_empty().alphanumeric())
    .field("age", IntegerSchema::new().required().min(18).positive());

Nested Model Validation

use adapters::prelude::*;

#[derive(Schema)]
struct Address {
    city: String,
    country: String,
}

#[derive(Schema)]
struct Profile {
    name: String,
    address: Address, // Child schema validated recursively!
}

Field Transformation Pipelines & Sanitization

Chaining data mapping and sanitization rules is highly expressive using functional pipelines. This is exceptionally useful when consuming legacy third-party Webhook payloads:

use adapters::prelude::*;
use adapters::transform::{Pipeline, FieldMapper};

// Create a field mapper to rename legacy API keys
let legacy_mapper = FieldMapper::new()
    .rename("txt_title", "title")
    .rename("usr_id", "user_id");

// Build a transformation pipeline
let pipeline = Pipeline::new()
    .push(legacy_mapper)
    .push(|mut value: Value| {
        // Custom sanitization: Force uppercase on the "title" key if present
        if let Some(obj) = value.as_object_mut() {
            if let Some(Value::String(s)) = obj.get_mut("title") {
                *s = s.to_uppercase();
            }
        }
        Ok(value)
    });

// Process a raw legacy payload
let legacy_payload = Value::Object(
    [
        ("txt_title".to_string(), Value::String("Adapters Guide".into())),
        ("usr_id".to_string(), Value::Int(99)),
    ]
    .into_iter()
    .collect()
);

let clean_value = pipeline.run(legacy_payload).unwrap();
println!("Transformed payload: {:?}", clean_value);
// Output will have "title" in uppercase, and "usr_id" renamed to "user_id"!

Alias Key Remapping

If you don't need runtime pipelines and only require direct structural key mapping from your JSON API payloads, use the #[schema(alias = "...")] helper:

use adapters::prelude::*;

#[derive(Schema, Debug)]
struct ApiConfig {
    /// Remaps "serverPort" in JSON directly to "port" in Rust
    #[schema(alias = "serverPort")]
    port: u16,

    /// Remaps "db_host_name" in JSON directly to "host" in Rust
    #[schema(alias = "db_host_name")]
    host: String,
}

Declarative Macro Reference Table

Configure your struct fields using the #[schema(...)] helper:

Performance & Benchmarks

Adapters is engineered for extreme data validation and parsing throughput. It implements high-performance zero-allocation parsing routines, compact error trees, and static struct validation maps.

To run benchmarks locally:

cargo bench

Building & Testing

# Check compiler requirements and clippy lints

cargo clippy --workspace --all-targets -- -D warnings


# Run all unit, integration, and doctests

cargo test --workspace --all-targets

Documentation

Online Documentation

Full structured guide and dynamic api walkthroughs are available natively at: https://muhammad-fiaz.github.io/adapters

Generating Local Documentation

To generate and view crate-level API documentation locally:

cargo doc --no-deps --open

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. See CONTRIBUTING.md for contribution guidelines.

License

MIT License - see LICENSE for details.

Links

• Documentation: https://muhammad-fiaz.github.io/adapters
• Repository: https://github.com/muhammad-fiaz/adapters
• Issues: https://github.com/muhammad-fiaz/adapters/issues