ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
//! The reading → LEAF VALUE map: [`ToOrderLeaves`], the ONE spelling an emitted cursor slot is
//! minted through.
//!
//! [`ToDatabaseOrderBy`](super::ToDatabaseOrderBy) says which leaves a term sorts by. This says what
//! ONE of those leaves is worth — the Rust type a level's boundary value has, and how to read it off
//! the row's own field. The two are the halves of one expansion: a term over a reordering citizen
//! becomes one ordinary level per leaf, and each level's cursor slot holds one leaf's value.
//!
//! # It is the SELECTOR, and the vocabulary it selects is the citizen's
//!
//! What a composite's leaves ARE is stated by the composite, at
//! [`OrderLeaves`](crate::OrderLeaves), beside the [`SEGMENTS`](crate::ColumnKind::SEGMENTS) and the
//! [`ORDER`](crate::ColumnKind::ORDER) it already writes. This module holds no citizen's answer and
//! grows no row per citizen. What it is FOR is the thing a macro cannot do: `at: MediaTimestamp` and
//! `title: String` are the same tokens, so an emission asked which of them has leaves would be
//! guessing. It writes one uniform spelling per column —
//! `<<T as DefaultMarker>::Marker as ToOrderLeaves>::Leaf` — and the compiler selects. A scalar's
//! row answers with the scalar itself, so a scalar column's cursor slot is exactly the type it was
//! before this map existed and its bytes do not move.
//!
//! That is [`shape`](crate::shape)'s arrangement carried one seam further: the same trick that lets
//! `ColumnKind` answer *how many columns* without the emitter deciding, answering *what one of them
//! is worth*.
//!
//! # `Db` is absent, and that is a measurement rather than a simplification
//!
//! [`ToDatabaseOrderBy`](super::ToDatabaseOrderBy) carries the dialect because what a database sorts
//! by is a database's answer. A LEAF's Rust type is not: `pts` is an `i64` in every dialect, the
//! type being the citizen's own. Carrying a parameter nothing reads would put a projection at a
//! generic `Db` on every `where` clause that names this — the four bound walls
//! [`ToCrossedComparison`](crate::comparison::ToCrossedComparison) documents — for an answer that
//! could not vary. What IS per-dialect about a leaf is how it BINDS, and that is
//! [`Carrier<Db>`](crate::Carrier)'s, on the leaf's own type, unchanged.
//!
//! # The COLLECTION readings have no row, and the absence is the design
//!
//! A collection is ONE column of the row whatever it holds, and its boundary is not a leaf of
//! anything: an array-stored one resumes at the whole LIST and a mirrored one at its companion
//! column's own bytes. Both are named directly by the emission, which reaches them through branches
//! it already writes — a collection is a fact a DECLARATION states, so unlike a width it is
//! something a macro can see. A row here would be a second way to spell a boundary that already has
//! one.

use crate::{
  OrderLeaves,
  marker::{
    BoolMarker, BytesMarker, CompositeMarker, DurationMarker, EnumMarker, Marker, ScalarMarker,
    StringMarker,
  },
};

/// An INTERPRETATION mapped to the VALUE one of its order LEVELS compares.
///
/// Implemented for the markers in [`crate::marker`] and for nothing else — the keying
/// [`ToDatabaseOrderBy`](super::ToDatabaseOrderBy) and
/// [`ToGraphqlFilter`](crate::ToGraphqlFilter) both take, for their reason: a type does not
/// determine its own reading. A declaration reaches this through
/// [`DefaultMarker`](crate::DefaultMarker).
///
/// # Every FLAT reading answers with ITSELF, and that is what keeps a scalar's cursor unmoved
///
/// One column, one leaf, and the leaf is the value: a scalar level's boundary is the scalar. So the
/// projection resolves to the very type the slot was minted with before this map existed, and every
/// byte of every scalar cursor is what it was.
///
/// # `Clone` is what a BOUNDARY costs, and it is not new
///
/// A cursor slot OWNS its value — it outlives the row it was read from and is handed back by a
/// client afterwards — so reading one off a borrowed field is a clone wherever it happens. The
/// emitted `value` already cloned at exactly this point; the bound states what that call was already
/// paying.
#[diagnostic::on_unimplemented(
  message = "`{Self}` has no order LEAF — nothing says what one level of it compares",
  label = "this column's reading cannot be a page boundary",
  note = "a flat reading answers with itself; a COMPOSITE answers through its own `OrderLeaves` \
          vocabulary, which is what a citizen publishes beside `ColumnKind::ORDER`"
)]
pub trait ToOrderLeaves: Marker {
  /// The value ONE level over this reading compares.
  type Leaf;

  /// The `at`-th LEAF of `value`, or [`None`] where it has none there.
  ///
  /// `at` is the LEAF numbering — the one [`width`](crate::width) counts — with the
  /// [`ORDER`](crate::ColumnKind::ORDER) permutation already spent, so one numbering reaches the
  /// citizen and the renderer alike.
  fn leaf(value: &Self::Marked, at: usize) -> Option<Self::Leaf>;
}

/// The seven FLAT readings, each answering with the value it is a reading of.
///
/// A macro rather than seven copies, for [`scalar_columns`](crate::column)'s reason one axis over:
/// the rows are identical and what differs is the marker's name, so a list is the honest shape and a
/// reading added to the flat family joins by being named here.
macro_rules! flat_leaves {
  ($($marker:ident),* $(,)?) => {
    $(
      impl<T: Clone> ToOrderLeaves for $marker<T> {
        type Leaf = T;

        #[inline]
        fn leaf(value: &T, _: usize) -> Option<T> {
          Some(value.clone())
        }
      }
    )*
  };
}

flat_leaves! {
  ScalarMarker,
  StringMarker,
  BytesMarker,
  EnumMarker,
  BoolMarker,
  DurationMarker,
}

#[cfg(feature = "flags")]
use crate::marker::FlagsMarker;

#[cfg(feature = "flags")]
flat_leaves! { FlagsMarker }

/// The ONE reading whose levels can be narrower than its value, delegating to the citizen's own
/// published vocabulary.
///
/// It reads [`OrderLeaves`] rather than holding a table of citizens, which is the framework-open
/// half of this design and the same half [`ToDatabaseOrderBy`](super::ToDatabaseOrderBy) takes for
/// the sequence: what a composite's leaves are worth is the composite's, so a downstream citizen
/// joins by writing one impl beside the [`ColumnKind`](crate::ColumnKind) it already writes.
impl<T: OrderLeaves> ToOrderLeaves for CompositeMarker<T> {
  type Leaf = T::Leaf;

  #[inline]
  fn leaf(value: &T, at: usize) -> Option<T::Leaf> {
    <T as OrderLeaves>::leaf(value, at)
  }
}

#[cfg(test)]
mod tests;