🔑 KeyPaths in Rust

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

Starter Guide

Installation

Add to your Cargo.toml:

[dependencies]
rust-key-paths = "2.0.2"
key-paths-derive = "2.0.2"

Basic usage

use std::sync::Arc;
use key_paths_derive::Kp;

#[derive(Debug, Kp)]
struct SomeComplexStruct {
    scsf: Option<SomeOtherStruct>,
    scfs2: Arc<std::sync::RwLock<SomeOtherStruct>>,
}

#[derive(Debug, Kp)]
struct SomeOtherStruct {
    sosf: Option<OneMoreStruct>,
}

#[derive(Debug, Kp)]
enum SomeEnum {
    A(String),
    B(Box<DarkStruct>),
}

#[derive(Debug, Kp)]
struct OneMoreStruct {
    omsf: Option<String>,
    omse: Option<SomeEnum>,
}

#[derive(Debug, Kp)]
struct DarkStruct {
    dsf: Option<String>,
}

impl SomeComplexStruct {
    fn new() -> Self {
        Self {
            scsf: Some(SomeOtherStruct {
                sosf: Some(OneMoreStruct {
                    omsf: Some(String::from("no value for now")),
                    omse: Some(SomeEnum::B(Box::new(DarkStruct {
                        dsf: Some(String::from("dark field")),
                    }))),
                }),
            }),
            scfs2: Arc::new(std::sync::RwLock::new(SomeOtherStruct {
                sosf: Some(OneMoreStruct {
                    omsf: Some(String::from("no value for now")),
                    omse: Some(SomeEnum::B(Box::new(DarkStruct {
                        dsf: Some(String::from("dark field")),
                    }))),
                }),
            })),
        }
    }
}
fn main() {
    let mut instance = SomeComplexStruct::new();

    SomeComplexStruct::scsf()
        .then(SomeOtherStruct::sosf())
        .then(OneMoreStruct::omse())
        .then(SomeEnum::b()) // Generated by Casepaths macro
        .then(DarkStruct::dsf())
        .get_mut(&mut instance).map(|x| {
        *x = String::from("🖖🏿🖖🏿🖖🏿🖖🏿");
    });

    println!("instance = {:?}", instance.scsf.unwrap().sosf.unwrap().omse.unwrap());
    // output - instance = B(DarkStruct { dsf: Some("🖖🏿🖖🏿🖖🏿🖖🏿") })
}

Composing keypaths

Chain through nested structures with then():

#[derive(Kp)]
struct Address { street: String }

#[derive(Kp)]
struct Person { address: Box<Address> }

let street_kp = Person::address().then(Address::street());
let street = street_kp.get(&person);  // Option<&String>

Partial and Any keypaths

Use #[derive(Pkp, Akp)] (requires Kp) to get type-erased keypath collections:

• PKp – partial_kps() returns Vec<PKp<Self>>; value type erased, root known
• AKp – any_kps() returns Vec<AKp>; both root and value type-erased for heterogeneous collections

Filter by value_type_id() / root_type_id() and read with get_as(). For writes, dispatch to the typed Kp (e.g. Person::name()) based on TypeId.

See examples: pkp_akp_filter_typeid, pkp_akp_read_write_convert.

More examples

cargo run --example kp_derive_showcase
cargo run --example pkp_akp_filter_typeid
cargo run --example pkp_akp_read_write_convert

Supported containers

The #[derive(Kp)] macro (from key-paths-derive) generates keypath accessors for these wrapper types:

Nested combinations (e.g. Option<Box<T>>, Option<Vec<T>>, Vec<Option<T>>) are supported.

Performance: Kp vs direct unwrap

Benchmark: nested Option chains and enum case paths (cargo bench --bench keypath_vs_unwrap).

Access overhead comes from closure indirection in the composed chain. Reusing a keypath (build once, use many times) matches direct unwrap; building the chain each time adds ~1–2 ns.

Would static keypaths help?

Yes. Static/const keypaths would:

• Remove creation cost entirely (no closure chain construction per use)
• Allow the compiler to inline the full traversal
• Likely close the gap to near-zero overhead vs manual unwrap

Currently, Kp::then() composes via closures that capture the previous step, so each access goes through a chain of function calls. A static keypath could flatten this to direct field offsets.

Performance: LockKp (Arc<Mutex>, Arc<RwLock>)

The keypath approach builds the chain each iteration and traverses through LockKp.then().then().then_async().then(); direct locks use sync_mutex.lock() then tokio_mutex.lock().await. Hot-path functions are annotated with #[inline] for improved performance.

10-level deep Arc<RwLock> benchmarks (leaf: f64)

Benchmark: 10 levels of nested Arc<RwLock<Next>>, reading/writing leaf f64. Run with:

• cargo bench --features parking_lot --bench ten_level_arc_rwlock
• cargo bench --bench ten_level_std_rwlock
• cargo bench --features tokio --bench ten_level_tokio_rwlock

Read (get leaf value):

Incr (write: leaf += 0.25):

Static keypath (chain built once, reused) matches or beats direct lock for sync RwLocks. For tokio, async keypath has higher overhead than direct .read().await/.write().await; direct lock is fastest.

📜 License

• Mozilla Public License 2.0