# Tuple projections
[](https://github.com/alekseysidorov/tuple-projections/actions/workflows/ci.yml)
[](#license)
`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
```rust
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:
```rust
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:
```rust
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`](docs/decisions.md).
## FoundationDB tuple prefix scans
[`examples/foundationdb_tuple_map.rs`](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](LICENSE-APACHE) or the [MIT license](LICENSE-MIT), at your option. Both license texts are included in each published crate archive.