🔑 KeyPaths in Rust

Key paths provide a safe, composable way to access and modify nested data in Rust. Inspired by **Swift's KeyPath ** system, this feature rich crate lets you work with struct fields and enum variants as first-class values.

rust-keypaths + keypaths-proc (Recommended)

• ✅ Faster performance, better compiler optimizations
• ✅ Write operations can be faster than manual unwrapping at deeper nesting levels
• ✅ Zero runtime overhead
• ✅ Better inlining - Compiler can optimize more aggressively
• ✅ Functional chains for Arc<Mutex<T>>/Arc<RwLock<T>> - Compose keypaths through sync primitives
• ✅ parking_lot support - Optional feature for faster locks
• ✅ Tokio support - Async keypath chains through Arc<tokio::sync::Mutex<T>> and Arc<tokio::sync::RwLock<T>>

[dependencies]
rust-keypaths = "1.7.0"
keypaths-proc = "1.7.0"

✨ Features

• ✅ Readable/Writable keypaths for struct fields
• ✅ Failable keypaths for Option<T> chains (_fr/_fw)
• ✅ Enum CasePaths (readable and writable prisms)
• ✅ Composition across structs, options and enum cases
• ✅ Iteration helpers over collections via keypaths
• ✅ Proc-macros: #[derive(Keypaths)] for structs/tuple-structs and enums, #[derive(Casepaths)] for enums
• ✅ Functional chains for Arc<Mutex<T>> and Arc<RwLock<T>> - Compose-first, apply-later pattern
• ✅ parking_lot support - Feature-gated support for faster synchronization primitives
• ✅ Tokio support - Async keypath chains through Arc<tokio::sync::Mutex<T>> and Arc<tokio::sync::RwLock<T>>
• ✅ Compile-time type safety - Invalid keypath compositions fail at compile time, preventing runtime errors

🚀 Examples

Deep Nested Composition with Box and Enums

This example demonstrates keypath composition through deeply nested structures with Box<T> and enum variants:

use keypaths_proc::{Casepaths, Keypaths};

#[derive(Debug, Keypaths)]
#[Writable]
struct SomeComplexStruct {
    scsf: Box<SomeOtherStruct>,
}

impl SomeComplexStruct {
    fn new() -> Self {
        Self {
            scsf: Box::new(SomeOtherStruct {
                sosf: OneMoreStruct {
                    omsf: String::from("no value for now"),
                    omse: SomeEnum::B(DarkStruct {
                        dsf: String::from("dark field"),
                    }),
                },
            }),
        }
    }
}

#[derive(Debug, Keypaths)]
#[Writable]
struct SomeOtherStruct {
    sosf: OneMoreStruct,
}

#[derive(Debug, Casepaths)]
#[Writable]
enum SomeEnum {
    A(String),
    B(DarkStruct),
}

#[derive(Debug, Keypaths)]
#[Writable]
struct OneMoreStruct {
    omsf: String,
    omse: SomeEnum,
}

#[derive(Debug, Keypaths)]
#[Writable]
struct DarkStruct {
    dsf: String,
}

fn main() {
    use rust_keypaths::WritableOptionalKeyPath;
    
    // Compose keypath through Box, nested structs, and enum variants
    // Using .then() method (works on stable Rust)
    let keypath = SomeComplexStruct::scsf_fw()
        .then(SomeOtherStruct::sosf_fw())
        .then(OneMoreStruct::omse_fw())
        .then(SomeEnum::b_case_fw())
        .then(DarkStruct::dsf_fw());
    
    // Alternatively, use the >> operator (requires nightly feature):
    // #![feature(impl_trait_in_assoc_type)]
    // let keypath = SomeComplexStruct::scsf_fw()
    //     >> SomeOtherStruct::sosf_fw()
    //     >> OneMoreStruct::omse_fw()
    //     >> SomeEnum::b_case_fw()
    //     >> DarkStruct::dsf_fw();
    
    let mut instance = SomeComplexStruct::new();
    
    // Mutate deeply nested field through composed keypath
    if let Some(dsf) = keypath.get_mut(&mut instance) {
        *dsf = String::from("we can update the field of struct with the other way unlocked by keypaths");
        println!("instance = {:?}", instance);
    }
}

Type Safety: Compile-Time Error Prevention

Keypaths provide compile-time type safety - if you try to compose keypaths that don't share the same root type, the compiler will catch the error before your code runs.

The Rule: When chaining keypaths with .then(), the Value type of the first keypath must match the Root type of the second keypath.

use keypaths_proc::Keypaths;

#[derive(Keypaths)]
#[All]
struct Person {
    name: String,
    address: Address,
}

#[derive(Keypaths)]
#[All]
struct Address {
    city: String,
}

#[derive(Keypaths)]
#[All]
struct Product {
    name: String,
}

fn main() {
    // ✅ CORRECT: Person -> Address -> city (all part of same hierarchy)
    let city_kp = Person::address_r()
        .then(Address::city_r());
    
    // ❌ COMPILE ERROR: Person::name_r() returns KeyPath<Person, String>
    //                   Product::name_r() expects Product as root, not String!
    // let invalid = Person::name_r()
    //     .then(Product::name_r());  // Error: expected `String`, found `Product`
}

What happens:

• ✅ Valid compositions compile successfully
• ❌ Invalid compositions fail at compile time with clear error messages
• 🛡️ No runtime errors - type mismatches are caught before execution
• 📝 Clear error messages - Rust compiler shows exactly what types are expected vs. found

This ensures that keypath chains are always type-safe and prevents bugs that would only be discovered at runtime.

Running the example:

cargo run --example type_safety_demo

parking_lot Support (Default for Mutex/RwLock)

⚠️ IMPORTANT: When using the derive macro, Mutex and RwLock default to parking_lot unless you explicitly use std::sync::Mutex or std::sync::RwLock.

[dependencies]
rust-keypaths = { version = "1.7.0", features = ["parking_lot"] }
keypaths-proc = "1.7.0"

Derive Macro Generated Methods for Locks

The derive macro generates helper methods for Arc<Mutex<T>> and Arc<RwLock<T>> fields:

use std::sync::Arc;
use parking_lot::RwLock;
use keypaths_proc::Keypaths;

#[derive(Keypaths)]
#[Writable]
struct Container {
    // This uses parking_lot::RwLock (default)
    data: Arc<RwLock<DataStruct>>,
    
    // This uses std::sync::RwLock (explicit)
    std_data: Arc<std::sync::RwLock<DataStruct>>,
}

#[derive(Keypaths)]
#[Writable]
struct DataStruct {
    name: String,
}

fn main() {
    let container = Container { /* ... */ };
    
    // Using generated _fr_at() for parking_lot (default)
    Container::data_fr_at(DataStruct::name_r())
        .get(&container, |value| {
            println!("Name: {}", value);
        });
    
    // Using generated _fw_at() for parking_lot (default)
    Container::data_fw_at(DataStruct::name_w())
        .get_mut(&container, |value| {
            *value = "New name".to_string();
        });
    
    // Using generated _fr_at() for std::sync::RwLock (explicit)
    Container::std_data_fr_at(DataStruct::name_r())
        .get(&container, |value| {
            println!("Name: {}", value);
        });
}

Key advantage: parking_lot locks never fail (no poisoning), so chain methods don't return Option for the lock operation itself.

Running the example:

cargo run --example parking_lot_chains --features parking_lot
cargo run --example parking_lot_nested_chain --features parking_lot

Tokio Support (Async Locks)

⚠️ IMPORTANT: Tokio support requires the tokio feature and uses tokio::sync::Mutex and tokio::sync::RwLock. All operations are async and must be awaited.

[dependencies]
rust-keypaths = { version = "1.7.0", features = ["tokio"] }
keypaths-proc = "1.7.0"
tokio = { version = "1.38.0", features = ["sync", "rt", "rt-multi-thread", "macros"] }

Derive Macro Generated Methods for Tokio Locks

The derive macro generates helper methods for Arc<tokio::sync::Mutex<T>> and Arc<tokio::sync::RwLock<T>> fields:

use std::sync::Arc;
use tokio::sync::{Mutex, RwLock};
use keypaths_proc::Keypaths;

#[derive(Keypaths)]
#[All]  // Generate all methods (readable, writable, owned)
struct AppState {
    user_data: Arc<tokio::sync::Mutex<UserData>>,
    config: Arc<tokio::sync::RwLock<Config>>,
    optional_cache: Option<Arc<tokio::sync::RwLock<Cache>>>,
}

#[derive(Keypaths)]
#[All]
struct UserData {
    name: String,
    email: String,
}

#[derive(Keypaths)]
#[All]
struct Config {
    api_key: String,
    timeout: u64,
}

#[derive(Keypaths)]
#[All]
struct Cache {
    entries: Vec<String>,
    size: usize,
}

#[tokio::main]
async fn main() {
    let state = AppState { /* ... */ };
    
    // Reading through Arc<tokio::sync::Mutex<T>> (async)
    AppState::user_data_fr_at(UserData::name_r())
        .get(&state, |name| {
            println!("User name: {}", name);
        })
        .await;
    
    // Writing through Arc<tokio::sync::Mutex<T>> (async)
    AppState::user_data_fw_at(UserData::name_w())
        .get_mut(&state, |name| {
            *name = "Bob".to_string();
        })
        .await;
    
    // Reading through Arc<tokio::sync::RwLock<T>> (async, read lock)
    AppState::config_fr_at(Config::api_key_r())
        .get(&state, |api_key| {
            println!("API key: {}", api_key);
        })
        .await;
    
    // Writing through Arc<tokio::sync::RwLock<T>> (async, write lock)
    AppState::config_fw_at(Config::timeout_w())
        .get_mut(&state, |timeout| {
            *timeout = 60;
        })
        .await;
    
    // Reading through optional Arc<tokio::sync::RwLock<T>> (async)
    if let Some(()) = AppState::optional_cache_fr()
        .chain_arc_tokio_rwlock_at_kp(Cache::size_r())
        .get(&state, |size| {
            println!("Cache size: {}", size);
        })
        .await
    {
        println!("Successfully read cache size");
    }
}

Key features:

• ✅ Async operations: All lock operations are async and must be awaited
• ✅ Read/write locks: RwLock supports concurrent reads with _fr_at() and exclusive writes with _fw_at()
• ✅ Optional chaining: Works seamlessly with Option<Arc<tokio::sync::Mutex<T>>> and Option<Arc<tokio::sync::RwLock<T>>>
• ✅ Nested composition: Chain through multiple levels of Tokio locks and nested structures

Running the example:

cargo run --example tokio_containers --features tokio

🌟 Showcase - Crates Using rust-key-paths

The rust-key-paths library is being used by several exciting crates in the Rust ecosystem:

• 🔍 rust-queries-builder - Type-safe, SQL-like queries for in-memory collections
• 🎭 rust-overture - Functional programming utilities and abstractions
• 🚀 rust-prelude-plus - Enhanced prelude with additional utilities and traits

🔗 Helpful Links & Resources

• 📘 type-safe property paths
• 📘 Swift KeyPath documentation
• 📘 Elm Architecture & Functional Lenses
• 📘 Rust Macros Book
• 📘 Category Theory in FP (for intuition)

💡 Why use KeyPaths?

• Avoids repetitive match / . chains.
• Encourages compositional design.
• Plays well with DDD (Domain-Driven Design) and Actor-based systems.
• Useful for reflection-like behaviors in Rust (without unsafe).
• High performance: essentially zero overhead for deep nested writes (10 levels)!

⚡ Performance

KeyPaths are optimized for performance with minimal overhead. Below are benchmark results comparing direct unwrap vs keypaths for 10-level deep nested access:

See benches/BENCHMARK_SUMMARY.md for detailed performance analysis.

Benchmarking RwLock Operations

The library includes comprehensive benchmarks for both parking_lot::RwLock and tokio::sync::RwLock operations:

parking_lot::RwLock benchmarks:

cargo bench --bench rwlock_write_deeply_nested --features parking_lot

Tokio RwLock benchmarks (read and write):

cargo bench --bench rwlock_write_deeply_nested --features parking_lot,tokio

The benchmarks compare:

• ✅ Keypath approach: Using _fr_at() and _fw_at() methods for readable and writable access
• ⚙️ Traditional approach: Manual read/write guards with nested field access

Benchmarks include:

• Deeply nested read/write operations through Arc<RwLock<T>>
• Optional field access (Option<T>)
• Multiple sequential operations
• Both synchronous (parking_lot) and asynchronous (tokio) primitives

Benchmark Results:

Key findings:

• ✅ parking_lot::RwLock: Keypaths show essentially identical performance (0-2.5% overhead) for single operations
• ✅ tokio::sync::RwLock: Keypaths show essentially identical performance (0-1% overhead) for async operations
• ⚡ Simple operations: Keypaths can be faster than manual guards in some cases (1-2% improvement)
• ⚠️ Multiple writes: Manual single guard is faster (33% overhead) - use single guard for multiple operations
• 🎯 Type safety: Minimal performance cost for significant type safety and composability benefits

Detailed Analysis:

• For detailed performance analysis, see benches/BENCHMARK_SUMMARY.md
• For performance optimization details, see benches/PERFORMANCE_ANALYSIS.md
• For complete benchmark results, see benches/BENCHMARK_RESULTS.md

🔄 Comparison with Other Lens Libraries

Key Advantages of rust-keypaths

1. ✅ Native Option support: Built-in failable keypaths (_fr/_fw) that compose seamlessly through Option<T> chains (unlike keypath, pl-lens, and lens-rs which require manual composition)
2. ✅ Enum CasePaths: First-class support for enum variant access (prisms) with #[derive(Casepaths)] (unique feature not found in keypath, pl-lens, or lens-rs)
3. ✅ Container types: Built-in support for Result, Mutex, RwLock, Arc, Rc, Box, and all standard collections (comprehensive container support unmatched by alternatives)
4. ✅ Functional chains for sync primitives: Compose keypaths through Arc<Mutex<T>> and Arc<RwLock<T>> with a clean, functional API
5. ✅ parking_lot support: Feature-gated support for faster parking_lot::Mutex and parking_lot::RwLock
6. ✅ Zero-cost abstractions: Minimal overhead (1.46x for reads, near-zero for writes) - benchmarked and optimized
7. ✅ Comprehensive derive macros: Automatic generation for structs (named and tuple), enums, and all container types
8. ✅ Swift-inspired API: Familiar API for developers coming from Swift's KeyPath system with .then() composition
9. ✅ Deep composition: Works seamlessly with 10+ levels of nesting without workarounds (tested and verified)
10. ✅ Type-safe composition: Full compile-time type checking with .then() method
11. ✅ Active development: Regularly maintained with comprehensive feature set and documentation

🛠 Roadmap

• Compose across structs, options and enum cases
• Derive macros for automatic keypath generation (Keypaths, Keypaths, Casepaths)
• Optional chaining with failable keypaths
• Smart pointer adapters (.for_arc(), .for_box(), .for_rc())
• Container support for Result, Mutex, RwLock, Weak, and collections
• Helper derive macros (ReadableKeypaths, WritableKeypaths)
• Functional chains for Arc<Mutex<T>> and Arc<RwLock<T>>
• parking_lot support for faster synchronization primitives
• Tokio support for async keypath chains through Arc<tokio::sync::Mutex<T>> and Arc<tokio::sync::RwLock<T>>
• Derive macros for complex multi-field enum variants

📜 License

• Mozilla Public License 2.0