Stillwater

"Still waters run pure"

A Rust library for pragmatic effect composition and validation, emphasizing the pure core, imperative shell pattern.

Philosophy

Stillwater embodies a simple idea:

Still = Pure functions (unchanging, referentially transparent)
Water = Effects (flowing, performing I/O)

Keep your business logic pure and calm like still water. Let effects flow at the boundaries.

What Problems Does It Solve?

1. "I want ALL validation errors, not just the first one"

use stillwater::Validation;

// Standard Result: stops at first error ❌
let email = validate_email(input)?;  // Stops here
let age = validate_age(input)?;      // Never reached if email fails

// Stillwater: accumulates all errors ✓
let user = Validation::all((
    validate_email(input),
    validate_age(input),
    validate_name(input),
))?;
// Returns: Err(vec![EmailError, AgeError, NameError])

2. "How do I test code with database calls?"

use stillwater::Effect;

// Pure business logic (no DB, easy to test)
fn calculate_discount(customer: &Customer, total: Money) -> Money {
    match customer.tier {
        Tier::Gold => total * 0.15,
        _ => total * 0.05,
    }
}

// Effects at boundaries (mockable)
fn process_order(id: OrderId) -> Effect<Invoice, Error, AppEnv> {
    IO::query(|db| db.fetch_order(id))        // I/O
        .and_then(|order| {
            let total = calculate_total(&order);  // Pure!
            IO::query(|db| db.fetch_customer(order.customer_id))
                .map(move |customer| (order, customer, total))
        })
        .map(|(order, customer, total)| {
            let discount = calculate_discount(&customer, total);  // Pure!
            create_invoice(order.id, total - discount)            // Pure!
        })
        .and_then(|invoice| IO::execute(|db| db.save(invoice))) // I/O
}

// Test with mock environment
#[test]
fn test_with_mock_db() {
    let env = MockEnv::new();
    let result = process_order(id).run(&env)?;
    assert_eq!(result.total, expected);
}

3. "My errors lose context as they bubble up"

use stillwater::Effect;

fetch_user(id)
    .context("Loading user profile")
    .and_then(|user| process_data(user))
    .context("Processing user data")
    .run(&env)?;

// Error output:
// Error: UserNotFound(12345)
//   -> Loading user profile
//   -> Processing user data

4. "I need clean dependency injection without passing parameters everywhere"

use stillwater::Effect;

#[derive(Clone)]
struct Config {
    timeout: u64,
    retries: u32,
}

// Functions don't need explicit config parameters
fn fetch_data() -> Effect<String, String, Config> {
    // Ask for config when needed
    Effect::asks(|cfg: &Config| {
        format!("Fetching with timeout={}", cfg.timeout)
    })
}

fn fetch_with_extended_timeout() -> Effect<String, String, Config> {
    // Temporarily modify environment for specific operations
    Effect::local(
        |cfg: &Config| Config { timeout: cfg.timeout * 2, ..*cfg },
        fetch_data()
    )
}

# tokio_test::block_on(async {
let config = Config { timeout: 30, retries: 3 };
let result = fetch_with_extended_timeout().run(&config).await?;
// Uses timeout=60 without changing the original config
# });

Core Features

Validation<T, E> - Accumulate all errors instead of short-circuiting
NonEmptyVec<T> - Type-safe non-empty collections with guaranteed head element
Effect<T, E, Env> - Separate pure logic from I/O effects
Parallel effect execution - Run independent effects concurrently with par_all(), race(), and par_all_limit()
Traverse and sequence - Transform collections with traverse() and sequence() for both validations and effects
- Validate entire collections with error accumulation
- Process collections with effects using fail-fast semantics
Reader pattern helpers - Clean dependency injection with ask(), asks(), and local()
Semigroup trait - Associative combination of values
- Extended implementations for HashMap, HashSet, BTreeMap, BTreeSet, Option
- Wrapper types: First, Last, Intersection for alternative semantics
Monoid trait - Identity elements for powerful composition patterns
Testing utilities - Ergonomic test helpers
- MockEnv builder for composing test environments
- Assertion macros: assert_success!, assert_failure!, assert_validation_errors!
- TestEffect wrapper for deterministic effect testing
- Optional proptest feature for property-based testing
Context chaining - Never lose error context
Zero-cost abstractions - Compiles to same code as hand-written
Works with ? operator - Integrates with Rust idioms
No heavy macros - Clear types, obvious behavior

Quick Start

use stillwater::{Validation, Effect, IO};

// 1. Validation with error accumulation
fn validate_user(input: UserInput) -> Validation<User, Vec<Error>> {
    Validation::all((
        validate_email(&input.email),
        validate_age(input.age),
        validate_name(&input.name),
    ))
    .map(|(email, age, name)| User { email, age, name })
}

// 2. Effect composition
fn create_user(input: UserInput) -> Effect<User, AppError, AppEnv> {
    // Validate (pure, accumulates errors)
    Effect::from_validation(validate_user(input))
        // Check if exists (I/O)
        .and_then(|user| {
            IO::query(|db| db.find_by_email(&user.email))
                .and_then(|existing| {
                    if existing.is_some() {
                        Effect::fail(AppError::EmailExists)
                    } else {
                        Effect::pure(user)
                    }
                })
        })
        // Save user (I/O)
        .and_then(|user| {
            IO::execute(|db| db.insert_user(&user))
                .map(|_| user)
        })
        .context("Creating new user")
}

// 3. Run at application boundary
let env = AppEnv { db, cache, logger };
let result = create_user(input).run(&env)?;

Why Stillwater?

Compared to existing solutions:

vs. frunk:

✓ Focused on practical use cases, not type-level programming
✓ Better documentation and examples
✓ Effect composition, not just validation

vs. monadic:

✓ No awkward macro syntax (rdrdo! { ... })
✓ Zero-cost (no boxing by default)
✓ Idiomatic Rust, not Haskell port

vs. hand-rolling:

✓ Validation accumulation built-in
✓ Error context handling
✓ Testability patterns established
✓ Composable, reusable

What makes it "Rust-first":

❌ No attempt at full monad abstraction (impossible without HKTs)
✓ Works with ? operator via Try trait
✓ Zero-cost via generics and monomorphization
✓ Integrates with async/await
✓ Borrows checker friendly
✓ Clear error messages

Installation

Add to your Cargo.toml:

[dependencies]
stillwater = "0.7"

# Optional: async support
stillwater = { version = "0.7", features = ["async"] }

# Optional: property-based testing
stillwater = { version = "0.7", features = ["proptest"] }

# Optional: multiple features
stillwater = { version = "0.7", features = ["async", "proptest"] }

Examples

Run any example with cargo run --example <name>:

Example	Demonstrates
form_validation	Validation error accumulation
nonempty	NonEmptyVec type for guaranteed non-empty collections
user_registration	Effect composition and I/O separation
error_context	Error trails for debugging
data_pipeline	Real-world ETL pipeline
testing_patterns	Testing pure vs effectful code
reader_pattern	Reader pattern with ask(), asks(), and local()
validation	Validation type and error accumulation patterns
effects	Effect type and composition patterns
parallel_effects	Parallel execution with par_all, race, and par_all_limit
io_patterns	IO module helpers for reading/writing
pipeline	Data transformation pipelines
traverse	Traverse and sequence for collections of validations and effects
monoid	Monoid and Semigroup traits for composition
extended_semigroup	Semigroup for HashMap, HashSet, Option, and wrapper types

See examples/ directory for full code.

Production Readiness

Status: 0.7 - Production Ready for Early Adopters

✅ 248 unit tests passing (includes property-based tests)
✅ 122 documentation tests passing
✅ Zero clippy warnings
✅ Comprehensive examples
✅ Full async support
✅ Testing utilities with MockEnv and assertion macros
✅ CI/CD pipeline with security audits

This library is stable and ready for use. The 0.x version indicates the API may evolve based on community feedback.

Documentation

📚 User Guide - Comprehensive tutorials
📖 API Docs - Full API reference
🤔 FAQ - Common questions
🏛️ Design - Architecture and decisions
💭 Philosophy - Core principles
🎯 Patterns - Common patterns and recipes
🔄 Comparison - vs other libraries

Migrating from Result

Already using Result everywhere? No problem! Stillwater integrates seamlessly:

// Your existing code works as-is
fn validate_email(email: &str) -> Result<Email, Error> {
    // ...
}

// Upgrade to accumulation when you need it
fn validate_form(input: FormInput) -> Validation<Form, Vec<Error>> {
    Validation::all((
        Validation::from_result(validate_email(&input.email)),
        Validation::from_result(validate_age(input.age)),
    ))
}

// Convert back to Result when needed
let result: Result<Form, Vec<Error>> = validation.into_result();

Start small, adopt progressively. Use Validation only where you need error accumulation.

Contributing

Contributions welcome! This is a young library with room to grow:

🐛 Bug reports and feature requests via issues
📖 Documentation improvements
🧪 More examples and use cases
💡 API feedback and design discussions

Before submitting PRs, please open an issue to discuss the change.

License

"Like a still pond with water flowing through it, stillwater keeps your pure business logic calm and testable while effects flow at the boundaries."

stillwater 0.7.0