tuple-projections 0.1.3

Type-safe left projections for tuples and product types.
Documentation

Tuple projections

tests License: MIT OR Apache-2.0

tuple-projections provides type-safe left projections for tuples and product types. If Whole = Prefix ++ Remainder, then Prefix: LeftProjectionOf<Whole, Remainder = Remainder>.

The crate is useful when a type-level prefix relation should be checked by the compiler, for example while defining ordered key prefixes for FoundationDB- style tuple keys. It provides the relation and tuple conversions, but leaves encoding, serialization, and database access to the surrounding application.

Tuple projections

use tuple_projections::LeftProjectionOf;

fn assert_projection<P, T, R>()
where
    P: LeftProjectionOf<T, Remainder = R>,
{
}

type Whole = (u64, String, bool);

assert_projection::<(), Whole, Whole>();
assert_projection::<(u64,), Whole, (String, bool)>();
assert_projection::<(u64, String), Whole, (bool,)>();
assert_projection::<Whole, Whole, ()>();

Product types

The TupleProjection derive gives a struct a canonical ordered tuple representation and its corresponding left projections:

use tuple_projections::{LeftProjectionOf, TupleProjection, TupleRepr};

#[derive(TupleProjection)]
struct EventKey {
    tenant: u64,
    timestamp: i64,
    id: String,
}

fn assert_projection<P, T, R>()
where
    P: LeftProjectionOf<T, Remainder = R>,
{
}

assert_projection::<(u64,), EventKey, (i64, String)>();
assert_projection::<(u64, i64), EventKey, (String,)>();

let key = EventKey {
    tenant: 42,
    timestamp: 1_700_000_000,
    id: String::from("event-7"),
};
assert_eq!(
    key.into_tuple(),
    (42, 1_700_000_000, String::from("event-7")),
);

EventKey is treated as the ordered product (u64, i64, String), following the declaration order of its fields. Ordinary Rust tuples implement TupleRepr as identity representations, so (u64, i64, String) is also its own tuple representation.

Field declaration order is semantic. It defines positional fields and projections; when field types differ, reordering also changes the tuple type. Treat a reorder as a key-layout change when the representation is ordered.

FoundationDB-style ordered keys

FoundationDB-style keyspaces often use an ordered tuple as a key and a shorter tuple as a key prefix. The projection trait lets an API express that a prefix belongs to a particular full-key shape without introducing a runtime matcher:

use tuple_projections::LeftProjectionOf;

fn range_for_prefix<Key, Prefix>(_prefix: Prefix)
where
    Prefix: LeftProjectionOf<Key>,
{
    // Build the database range using the application's tuple encoder.
}

type EventKey = (u64, i64, String);
range_for_prefix::<EventKey, _>((42_u64,));
range_for_prefix::<EventKey, _>((42_u64, 1_700_000_000_i64));

This crate intentionally does not depend on FoundationDB or any particular encoding format. It only describes the compile-time relationship that an ordered-key adapter can use.

More design context and comparisons with related crates are recorded in docs/decisions.md.

FoundationDB tuple prefix scans

examples/foundationdb_tuple_map.rs builds a small in-memory MapIndex<K, V> to demonstrate how typed tuple projections can drive prefix scans over FoundationDB-compatible keys. Its EventKey is a named struct with #[derive(TupleProjection)], so CRUD uses the domain type while the derive supplies its canonical (tenant_id, sequence_number) representation and compile-time prefix relations. Querying with (tenant_id,) returns that tenant's events in key order, while querying with a full (tenant_id, sequence_number) projection selects that exact entry.

The example uses the standalone foundationdb-tuple crate to pack tuple keys into sortable bytes and to obtain a key range for a tuple subspace. Since the encoded prefix keys are adjacent in BTreeMap order, iteration seeks directly to the range instead of checking every key (O(log n + matches)). The derived LeftProjectionOf implementations make an invalid prefix shape a compile-time error; the byte encoding and range selection then provide the runtime behavior. Decoding a stored key back into EventKey uses the derived TupleRepr conversion as well.

This separation is useful for ordered-key APIs, including FoundationDB-style keyspaces: the projection captures the structural rule (“this is a leading part of the key”), while the storage adapter chooses how that prefix becomes a range. The example is deliberately not a database client: values live in a local BTreeMap, it opens no FoundationDB connection, and foundationdb-tuple is only a development dependency. Run it with cargo run --example foundationdb_tuple_map.

License

Each crate is licensed under either of the Apache License, Version 2.0 or the MIT license, at your option. Both license texts are included in each published crate archive.