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
//! One page of a written order: [`Page`], and the [`Edge`] each of its rows arrives as.

use crate::Cursor;

/// One row of a page: the record, and the cursor that resumes AT it.
///
/// # Every edge carries a cursor, including an offset page's
///
/// A page reached by `skip` is browsed by number and resumed by position, and both are the same set
/// of rows — so its edges carry keyset cursors exactly as a `after`-resumed page's do. That is what
/// lets a client browse by offset and then switch to cursor resumption without re-issuing the query
/// under different arguments, and it costs nothing: the values a cursor is minted from are already
/// in the row.
///
/// # The cursor is TYPED here and a string only at the wire
///
/// [`Cursor::encode`] is where it becomes the one opaque string a client holds. Holding the typed
/// value up to that point is what keeps the boundary honest — an engine that handed out strings
/// would have to parse its own output back to page from it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Edge<R, V> {
  node: R,
  cursor: Cursor<V>,
}

impl<R, V> Edge<R, V> {
  /// The row `node` sits at, in the order `cursor` was minted under.
  #[inline]
  #[must_use]
  pub const fn new(node: R, cursor: Cursor<V>) -> Self {
    Self { node, cursor }
  }

  /// The record itself.
  #[inline]
  #[must_use]
  pub const fn node(&self) -> &R {
    &self.node
  }

  /// The cursor at this row.
  #[inline]
  #[must_use]
  pub const fn cursor(&self) -> &Cursor<V> {
    &self.cursor
  }

  /// The two halves, taken apart.
  #[inline]
  #[must_use]
  pub fn into_parts(self) -> (R, Cursor<V>) {
    (self.node, self.cursor)
  }
}

/// A page of a written order: its rows, and whether there is more on either side of them.
///
/// # The booleans are not symmetrical, and the asymmetry is stated rather than hidden
///
/// A page is fetched one row wider than it was asked for, and the extra row is what answers *is
/// there more this way*. That answer is exact for the direction the walk RAN, and only for that
/// one: a forward page knows there are more rows after it because it saw one, and knows nothing
/// about what lies before it except that the client asked to resume somewhere. So the other
/// boolean is `a position was given` — relay's own permitted approximation, which never says *no
/// more* when there is more.
///
/// | walk | `has_next_page` | `has_previous_page` |
/// |---|---|---|
/// | forward | EXACT — the extra row | the request carried an `after` or a `skip` |
/// | backward | the request carried a `before` or a `skip` | EXACT — the extra row |
///
/// The two rows are one rule read from either end, which is what makes the backward walk the same
/// machinery rather than a second implementation: it runs the order inverted and the page is
/// re-reversed into display order before it gets here.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Page<R, V> {
  edges: Box<[Edge<R, V>]>,
  has_next: bool,
  has_previous: bool,
}

impl<R, V> Page<R, V> {
  /// A page of `edges`, in DISPLAY order, with what is known about either side of it.
  ///
  /// Display order means the order as written, whichever way the walk ran — a backward page is
  /// re-reversed by the engine before it is built, so nothing downstream has to know which
  /// direction produced it.
  #[inline]
  #[must_use]
  pub fn new(edges: impl Into<Box<[Edge<R, V>]>>, has_next: bool, has_previous: bool) -> Self {
    Self {
      edges: edges.into(),
      has_next,
      has_previous,
    }
  }

  /// The rows, in display order.
  #[inline]
  #[must_use]
  pub fn edges(&self) -> &[Edge<R, V>] {
    &self.edges
  }

  /// The rows, owned.
  #[inline]
  #[must_use]
  pub fn into_edges(self) -> Box<[Edge<R, V>]> {
    self.edges
  }

  /// Whether a row exists after the last one here.
  #[inline]
  #[must_use]
  pub const fn has_next_page(&self) -> bool {
    self.has_next
  }

  /// Whether a row exists before the first one here.
  #[inline]
  #[must_use]
  pub const fn has_previous_page(&self) -> bool {
    self.has_previous
  }

  /// The cursor at the first row, or [`None`] for an empty page.
  #[inline]
  #[must_use]
  pub fn start_cursor(&self) -> Option<&Cursor<V>> {
    self.edges.first().map(Edge::cursor)
  }

  /// The cursor at the last row, or [`None`] for an empty page.
  #[inline]
  #[must_use]
  pub fn end_cursor(&self) -> Option<&Cursor<V>> {
    self.edges.last().map(Edge::cursor)
  }

  /// How many rows this page holds.
  #[inline]
  #[must_use]
  pub const fn len(&self) -> usize {
    self.edges.len()
  }

  /// Whether the page holds no rows — which a page past the end legitimately does.
  #[inline]
  #[must_use]
  pub const fn is_empty(&self) -> bool {
    self.edges.is_empty()
  }
}

#[cfg(test)]
mod tests;