Tuple projections
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 LeftProjectionOf;
type Whole = ;
;
;
;
;
Product types
The TupleProjection derive gives a struct a canonical ordered tuple
representation and its corresponding left projections:
use ;
;
;
let key = EventKey ;
assert_eq!;
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 LeftProjectionOf;
type EventKey = ;
;
;
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.