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
//! What a relation predicate refuses with, whichever backend renders it: [`RelationWidthError`] and
//! [`RelationDepthError`].
//!
//! # The payloads are neutral where the ENUMS holding them are not
//!
//! [`SqlLoweringError`](super::sql::SqlLoweringError) and
//! [`MongoLoweringError`](super::mongo::MongoLoweringError) are two vocabularies, because what a
//! dialect can say no to is not what a document store can. These two causes are in BOTH, and they
//! carry the same three facts either way: a relation joins one column to one column whichever
//! language spells the join, and an alias table runs out at the same depth whichever engine indexes
//! it.
//!
//! So they sit here rather than once per family. Two structs of the same shape under two names would
//! be a caller converting between them to report one fact, and a message that could drift between
//! the backends for a reason neither of them has.
//!
//! They started in [`sql`](super::sql), which is where the first engine put them, and the second
//! backend is what moved them — the same road [`CrossingError`](crate::query::CrossingError) and
//! [`DEPTH_CEILING`](crate::query::DEPTH_CEILING) took. Both families re-export them, so every path
//! a reader already knows keeps resolving.

use crate::FieldName;

/// The payload of a relation refused for its ADDRESS: the row addressed by several columns, and how
/// many address it.
///
/// A `ref` field carries `<Target as Identifiable>::Id`, and an id is ONE column because every
/// table's id is unique. So the forward semi-join has one name to project and the reverse
/// correlation one name to compare against, and a row addressed by two leaves the second side with
/// nothing to meet.
///
/// It names the row at fault rather than the relation, because that is what a caller changes: either
/// the [`RecordAddress`](crate::RecordAddress) the position was given is the wrong row, or the row
/// really is compound and the relation belongs on its id instead.
///
/// `Copy` with the enums that hold it, both halves being a `'static` name and a count.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RelationWidthError {
  table: &'static FieldName,
  columns: usize,
}

impl RelationWidthError {
  /// Record that `table` is addressed by `columns` columns where a relation needs one.
  #[inline]
  pub(crate) const fn new(table: &'static FieldName, columns: usize) -> Self {
    Self { table, columns }
  }

  /// The row whose address is too wide.
  #[inline]
  pub const fn table(&self) -> &'static FieldName {
    self.table
  }

  /// How many columns address it.
  #[inline]
  pub const fn columns(&self) -> usize {
    self.columns
  }
}

/// The payload of a relation refused for its DEPTH: the row whose alias was asked for, the depth
/// asked, and how many depths its aliases were minted for.
///
/// A nested relation renames its scope per LEVEL — depth one inside depth zero, and so on — and a
/// row's alias table holds one name per level up to the depth its declaration minted, which is
/// [`DEPTH_CEILING`](crate::query::DEPTH_CEILING) unless `<db>(alias(depth = …))` named
/// another. Past the last entry there is no name left to take, and the alternative to refusing is
/// REUSING one — which is silent on both backends and silent in two different ways. SQL resolves a
/// reference to the innermost scope that has a match, so a repeated alias correlates the wrong two
/// rows and the statement still answers; a repeated MongoDB join field is written twice in one
/// document, so the second `$lookup` OVERWRITES the first and the predicate that reads it tests a
/// set nobody asked about.
///
/// The CEILING carried is the alias table's own length rather than the constant, so the message
/// cannot describe a row that was minted to a different depth — and that is what lets the depth BE a
/// declaration's choice: a row minted sixteen deep refuses at sixteen, saying sixteen, with no
/// engine anywhere holding a second copy of the number.
///
/// `Copy` with the enums that hold it — a `'static` name and two counts.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RelationDepthError {
  table: &'static FieldName,
  depth: usize,
  ceiling: usize,
}

impl RelationDepthError {
  /// Record that `table` was asked for its alias at `depth`, where `ceiling` were minted.
  #[inline]
  pub(crate) const fn new(table: &'static FieldName, depth: usize, ceiling: usize) -> Self {
    Self {
      table,
      depth,
      ceiling,
    }
  }

  /// The row whose alias ran out.
  #[inline]
  pub const fn table(&self) -> &'static FieldName {
    self.table
  }

  /// The nesting depth asked for.
  #[inline]
  pub const fn depth(&self) -> usize {
    self.depth
  }

  /// How many depths that row's aliases were minted for.
  #[inline]
  pub const fn ceiling(&self) -> usize {
    self.ceiling
  }
}