🔑 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.

Installation

Add to your Cargo.toml:

[dependencies]
rust-key-paths = "2.9.8"
key-paths-derive = "2.6.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())
        .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.

Features

More examples

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.

arcswap (optional): atomically swappable Arc

Enable arcswap on rust-key-paths and add the same dependency key in your crate so generated paths resolve:

[dependencies]
rust-key-paths = { version = "2.9.8", features = ["arcswap"] }
arcswap = { package = "arc-swap", version = "1.9" }

When to use ArcSwap instead of RwLock<Arc<T>>: you reload or publish whole snapshots (store / swap / rcu) and many threads read the current snapshot most of the time. Reads use load() (default strategy: low-latency, lock-free snapshots) instead of contending on a reader–writer lock. Prefer a static or LazyLock holding an ArcSwap when a single global pointer is enough; wrap in Arc<ArcSwap<T>> when the swap container is created at runtime and shared across threads (the outer Arc is only for sharing the container; hot-path reads touch the inner atomic pointer, not the Arc refcount).

When not to: you need a true in-place &mut T through a lock for arbitrary mutation of T inside the guard. ArcSwap stores an Arc<T>; updates replace the pointer. Use store / rcu at the call site for writes.

Chaining: compose the full lock path on the first SyncKp with .then(…) / .then_sync(…) (see examples/box_keypath_arcswap.rs). Import ChainExt for Kp::then_sync. Nested then_sync from the crate root can infer a 'static root in some compositions; if you hit that, call an inner SyncKp from a & to the inner struct (same example).

pin_project #[pin] fields (optional feature)

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

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: box_keypath benchmark

Benchmark file: benches/box_keypath_bench.rs

Run with:

cargo bench --bench box_keypath_bench

Read path (scsf -> sosf -> omse -> B -> dsf)

Write path (scsf -> sosf -> omse -> B -> dsf)

These numbers are from Criterion's reported confidence ranges on this machine. In this benchmark, keypaths are very close to direct traversal for reads and only slightly slower for writes.

Keypath size

From examples/box_keypath.rs, the composed keypath prints:

size of kp = 0

So this composed kp is zero-sized (no captured runtime state).

Performance: arcswap_keypath benchmark

Benchmark file: benches/arcswap_keypath_bench.rs (requires --features arcswap).

cargo bench --bench arcswap_keypath_bench --features arcswap

Read path (scsf → ArcSwap load → omse → B → dsf)

Compared to load_full() plus a manual match on the loaded OneMoreStruct (which clones the inner Arc on every read), the composed keypath uses load() under the hood and stays on the snapshot for the rest of the chain.

Your numbers will vary by CPU and optimization level; treat this as a sanity check that keypath traversal stays in the same ballpark as a small manual load, while load_full + clone is heavier by design when you need an owned Arc.

Skills guide (AI assistants & tooling)

Usage-focused patterns—versions/features, #[derive(Kp)], chaining, sync/async locks, deep nesting, migrating from Option / Java-style getter chains—live in Skills.md at the repository root.

Paths to reference: Skills.md (repo root), or ./Skills.md from this README’s directory. Point Cursor Rules, Agent Skills, or similar project instructions at that file so assistants can resolve the path and include it in context.

📜 License

• Mozilla Public License 2.0