🔑 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.6"
key-paths-derive = "2.0.6"

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())
        .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.

GPU / wgpu (key-paths-iter, optional)

The key-paths-iter crate can run numeric keypaths (e.g. f32) on the GPU via wgpu. Two styles:

AKp runner (wgpu module): IntoNumericAKp from Kp, AKpTier::Numeric / Arbitrary, AKpRunner. Examples: kp_pkp_wgpu, akp_wgpu_runner.
Kp-only (kp_gpu module): no AKp/PKp — .map_gpu(wgsl), .par_gpu(wgsl, roots, ctx), GpuKpRunner. Examples: kp_gpu_example, kp_gpu_vec_example, kp_gpu_practical_app (finance: Monte Carlo, batch options, stress-test). Kp with value Vec<V>: .map_gpu_vec(wgsl) for one dispatch over the vector.

Run benchmarks: cargo bench --bench akp_cpu_bench. Typical results (MacBook Air M1):

Roots	Serial (CPU)	Parallel CPU (Rayon)	Parallel GPU (wgpu)
1,000	~35 µs	~86 µs	~1.6 ms
10,000	~350 µs	~425 µs	~1.9 ms
50,000	~1.8 ms	~1.8 ms	~3.7 ms
100,000	~3.7 ms	~3.7 ms	~5.5 ms

For this lightweight transform, CPU wins; GPU pays off for larger batches or heavier per-element math.

Features

Feature	Description
`parking_lot`	Use `parking_lot::Mutex` / `RwLock` instead of `std::sync`
`tokio`	Async lock support (`tokio::sync::Mutex`, `RwLock`)
`pin_project`	Enable `#[pin]` field support for pin-project compatibility

More examples

cargo run --example kp_derive_showcase
cargo run --example pkp_akp_filter_typeid
cargo run --example pkp_akp_read_write_convert
# Kp/Pkp + wgpu (key-paths-iter with gpu feature)
cargo run --example kp_pkp_wgpu
cargo run --example akp_wgpu_runner
cargo run --example kp_gpu_example
cargo run --example kp_gpu_vec_example
cargo run --example kp_gpu_practical_app
# Box and Pin support
cargo run --example box_and_pin_example
# pin_project #[pin] fields
cargo run --example pin_project_example --features pin_project
cargo run --example pin_project_fair_race --features "pin_project,tokio"
# Deadlock prevention (parallel execution)
cargo run --example deadlock_prevention_sync --features parking_lot
cargo run --example deadlock_prevention_async --features tokio

Supported containers

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

Container	Access	Notes
`Option<T>`	`field()`	Unwraps to inner type
`Box<T>`	`field()`	Derefs to inner
`Pin<T>`, `Pin<Box<T>>`	`field()`, `field_inner()`	Container + inner (when `T: Unpin`)
`Rc<T>`, `Arc<T>`	`field()`	Derefs; mut when unique ref
`Vec<T>`	`field()`, `field_at(i)`	Container + index access
`HashMap<K,V>`, `BTreeMap<K,V>`	`field_at(k)`	Key-based access
`HashSet<T>`, `BTreeSet<T>`	`field()`	Container identity
`VecDeque<T>`, `LinkedList<T>`, `BinaryHeap<T>`	`field()`, `field_at(i)`	Index where applicable
`Result<T,E>`	`field()`	Unwraps `Ok`
`Cow<'_, T>`	`field()`	`as_ref` / `to_mut`
`Option<Cow<'_, T>>`	`field()`	Optional Cow unwrap
`std::sync::Mutex<T>`, `std::sync::RwLock<T>`	`field()`	Container (use `LockKp` for lock-through)
`Arc<Mutex<T>>`, `Arc<RwLock<T>>`	`field()`, `field_lock()`	Lock-through via `LockKp`
`tokio::sync::Mutex`, `tokio::sync::RwLock`	`field_async()`	Async lock-through (tokio feature)
`parking_lot::Mutex`, `parking_lot::RwLock`	`field()`, `field_lock()`	parking_lot feature

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

pin_project `#[pin]` fields (optional feature)

When using pin-project, mark pinned fields with #[pin]. The derive generates:

`#[pin]` field type	Access	Notes
Plain (e.g. `i32`)	`field()`, `field_pinned()`	Pinned projection via `this.project()`
`Future`	`field()`, `field_pinned()`, `field_await()`	Poll through `Pin<&mut Self>`
`Box<dyn Future<Output=T>>`	`field()`, `field_pinned()`, `field_await()`	Same for boxed futures

Enable with pin_project feature and add #[pin_project] to your struct:

#[pin_project]
#[derive(Kp)]
struct WithPinnedFuture {
    fair: bool,
    #[pin]
    fut: Pin<Box<dyn Future<Output = String> + Send>>,
}

Examples: pin_project_example, pin_project_fair_race (FairRaceFuture use case).

Performance: Kp vs direct unwrap

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

Scenario	Keypath	Direct unwrap	Overhead
100× reuse (3-level)	~36.6 ns	~36.7 ns	~1x
100× reuse (5-level)	~52.3 ns	~52.5 ns	~1x

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>)

Operation	Keypath	Direct Locks	Overhead
Read	~241 ns	~117 ns	~2.1x
Write	~239 ns	~114 ns	~2.1x

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

Incr (write: leaf += 0.25):

RwLock implementation	keypath_static	keypath_dynamic	direct_lock
parking_lot	~34 ns	~41 ns	~39 ns
std::sync	~46 ns	~54 ns	~46 ns
tokio::sync	~1.79 µs	~1.78 µs	~278 ns

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🔑 KeyPaths in Rust

Starter Guide

Installation

Basic usage

Composing keypaths

Partial and Any keypaths

GPU / wgpu (key-paths-iter, optional)

Features

More examples

Supported containers

pin_project `#[pin]` fields (optional feature)

Performance: Kp vs direct unwrap

Would static keypaths help?

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

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

📜 License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

🔑 KeyPaths in Rust

Starter Guide

Installation

Basic usage

Composing keypaths

Partial and Any keypaths

GPU / wgpu (key-paths-iter, optional)

Features

More examples

Supported containers

pin_project #[pin] fields (optional feature)

Performance: Kp vs direct unwrap

Would static keypaths help?

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

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

📜 License

pin_project `#[pin]` fields (optional feature)