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
//! [`ColumnEq`]: what it means for two stored values of one column to be THE SAME value, stated by
//! the type rather than demanded of it.
//!
//! # The demand this face replaces
//!
//! A record's emitted row and its emitted page cursor both carried `#[derive(PartialEq)]`, so every
//! declared field type was required to be [`PartialEq`] — a std trait asked for by generated code an
//! author cannot edit. `regex::Regex` implements none, and cannot be given one anywhere but in
//! `regex`'s own crate (`impl PartialEq for regex::Regex` is `E0117` here and in every other), so a
//! pattern column made a declaration fail to compile inside its own expansion.
//!
//! The answer is not to drop row equality — a row that cannot be compared is a row no test can
//! assert on — but to stop asking a foreign trait of a foreign type. The emission now writes the
//! `PartialEq` impl itself, folding [`column_eq`](ColumnEq::column_eq) over the fields, and this
//! face is what each field answers. **Row equality is unchanged for every type whose row is `==`**,
//! which is every type this crate shipped before the pattern arrived.
//!
//! # One row per type, never a blanket
//!
//! `impl<T: PartialEq> ColumnEq for T` would give every existing type its row for free and is the
//! obvious surface. It cannot stand: `regex::Regex` needs a row of its own, and coherence cannot
//! prove that `regex` will never publish a `PartialEq`, so the two impls overlap (`E0119`). The
//! same measurement [`Assemble`](crate::Assemble) records — *a row per type rather than a blanket* —
//! therefore holds here for a second, independent reason, and the roster is written out beside the
//! [`ColumnKind`](crate::ColumnKind) rows it tracks.
//!
//! # It names no database, exactly as a width does not
//!
//! Whether two values are the same value is not a dialect's question. The row is written once, in
//! the module that states what a field *is*, and every backend's emission reads the same answer —
//! which is what keeps a record's SQLite row and its MongoDB row agreeing about equality.

/// Whether two values of this column type are the same value.
///
/// # It is [`PartialEq`] for a type that has one, and the row says so
///
/// Almost every row in this crate is `self == other`, written through the same table that states the
/// type's width. What the face buys is the type that has no `PartialEq` and cannot be given one:
/// its row says what sameness means for it, in its own terms, in the crate that stores it.
///
/// # The contract is `PartialEq`'s, because that is what it is spent as
///
/// An emitted `impl PartialEq for <Record><Db>` folds this over the row's fields, so a row inherits
/// whatever this row promises: symmetry and transitivity where the type has them, and no reflexivity
/// claim (`f64`'s `NaN` is a column value, and `NaN != NaN` stays true through the fold). A row that
/// disagreed with its own type's `==` would make a record's equality mean one thing at the field and
/// another at the row, so a type carrying `PartialEq` writes `self == other` and nothing else.
///
/// # Joining from outside
///
/// A downstream citizen adds `impl ColumnEq for MyScalar { fn column_eq(&self, other: &Self) -> bool
/// { self == other } }` beside the [`ColumnKind`](crate::ColumnKind) row it already writes.
/// `#[derive(ingraph::Id)]`, `#[ingraph::enumeration]`, `#[ingraph::flags]`, `#[ingraph::newtype]`
/// and `#[ingraph::fields]` write it for what they declare, so a declaration road never has to.
///
/// # Examples
///
/// ```
/// use ingraph::ColumnEq;
///
/// assert!(7i64.column_eq(&7));
/// assert!(!"a".column_eq(&"b"));
/// // The row is `PartialEq`'s, so a partial equivalence stays partial.
/// assert!(!f64::NAN.column_eq(&f64::NAN));
/// ```
///
/// An absent value is the same as an absent value, and never the same as a present one:
///
/// ```
/// use ingraph::ColumnEq;
///
/// assert!(None::<i64>.column_eq(&None));
/// assert!(!None::<i64>.column_eq(&Some(0)));
/// ```
#[diagnostic::on_unimplemented(
  message = "`{Self}` has no column equality: this crate cannot say when two of them are the same \
             stored value",
  label = "this declaration stores a column of `{Self}`",
  note = "a record's row and its page cursor are compared field by field through `ColumnEq`, which \
          replaced the `PartialEq` those two types used to derive — so a field type states its own \
          sameness instead of being required to carry a std trait",
  note = "a type that already has `PartialEq` joins with a one-line row beside its `ColumnKind` \
          one — `impl ingraph::ColumnEq for MyScalar`, whose `column_eq` is `self == other`",
  note = "a type declared through `#[derive(ingraph::Id)]`, `#[ingraph::enumeration]`, \
          `#[ingraph::flags]`, `#[ingraph::newtype]` or `#[ingraph::fields]` is given this row by \
          the declaration, so an unsatisfied bound here names a type written by hand",
  note = "under `#[ingraph::record(…)]` the road out is `<db>(type = \"…\")`, naming a stored form \
          that HAS a row, with `from`/`into` beside it"
)]
pub trait ColumnEq {
  /// Whether `self` and `other` are the same stored value.
  fn column_eq(&self, other: &Self) -> bool;
}

/// One row per type, each spending the type's own [`PartialEq`].
///
/// A type whose sameness is NOT `==` — because it has no `PartialEq` at all, or because what it
/// STORES is narrower than what it holds — is written out as an impl of its own instead, where the
/// identity it is compared under can be stated and shown. `regex::Regex` is the first such type;
/// see its row in [`column`](crate::column).
macro_rules! column_eq {
  ($( $ty:ty ),+ $(,)?) => {
    $(
      impl $crate::column::ColumnEq for $ty {
        #[inline]
        fn column_eq(&self, other: &Self) -> ::core::primitive::bool {
          self == other
        }
      }
    )+
  };
}

pub(crate) use column_eq;

// THE WRAPPERS, each delegating to what it wraps — and the BOUND is the membership rule, exactly as
// it is on the `ColumnKind` rows these mirror. A holder is the same as a holder when what they hold
// is the same, so none of them decides anything on its own.

/// A borrow is the same as a borrow when what they point at is.
impl<T: ColumnEq + ?Sized> ColumnEq for &T {
  #[inline]
  fn column_eq(&self, other: &Self) -> bool {
    T::column_eq(self, other)
  }
}

/// Absent is absent, present is present, and the two are never each other.
///
/// This is the shape a nullable column actually takes — `Option<T>` is what an `optional` field's
/// row field holds — so it is the row most emitted comparisons reach.
impl<T: ColumnEq> ColumnEq for Option<T> {
  #[inline]
  fn column_eq(&self, other: &Self) -> bool {
    match (self, other) {
      (Some(this), Some(that)) => this.column_eq(that),
      (None, None) => true,
      _ => false,
    }
  }
}

/// A collection is the same as a collection when it holds the same elements in the same order.
///
/// Length first, which is what `PartialEq for Vec<T>` does too — and the order is load-bearing: an
/// edge-stored collection is read back in its stored sequence, so two orders are two values.
impl<T: ColumnEq> ColumnEq for Vec<T> {
  #[inline]
  fn column_eq(&self, other: &Self) -> bool {
    self.len() == other.len()
      && self
        .iter()
        .zip(other.iter())
        .all(|(this, that)| this.column_eq(that))
  }
}

#[cfg(test)]
mod tests;