tuple-projections 0.1.3

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

[![tests](https://github.com/alekseysidorov/tuple-projections/actions/workflows/ci.yml/badge.svg)](https://github.com/alekseysidorov/tuple-projections/actions/workflows/ci.yml)
[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)

<!-- ANCHOR: description -->
`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.
<!-- ANCHOR_END: description -->

## Tuple projections

<!-- ANCHOR: tuple_projection_example -->
```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, ()>();
```
<!-- ANCHOR_END: tuple_projection_example -->

## Product types

<!-- ANCHOR: product_example -->
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")),
);
```
<!-- ANCHOR_END: product_example -->

`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

<!-- ANCHOR: fdb_example -->
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.
<!-- ANCHOR_END: fdb_example -->

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.