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 walk owes: every node once, in declaration order, and nothing after a refusal.
//!
//! The walk under test is hand-written, which is what a graph root's expansion emits — see
//! `ingraph-derive`'s `Ingraph`, whose fixtures put the same three claims to a generated one. Here
//! the claims are about the VISITOR vocabulary itself, so the driver is written out rather than
//! expanded.

use super::TypeVisitor;
use crate::{Column, Describe, FieldName, RecordAddress, Table};

/// The database these descriptors are written for — a stand-in, since a walk renders nothing.
struct Db;

/// A second one, so the refusal a visitor built for one database gives another is reachable.
struct Other;

impl crate::Habitat for Db {
  type Blueprint = Table;
}

impl crate::Habitat for Other {
  type Blueprint = Table;
}

struct Media;
struct Clip;
struct Caption;

impl Describe<Db> for Media {
  const BLUEPRINT: Table = Table::new(
    RecordAddress::new(FieldName::new("media"), &[FieldName::new("id")]),
    &[Column::new(FieldName::new("id"), "INTEGER", false)],
  );
}

impl Describe<Db> for Clip {
  const BLUEPRINT: Table = Table::new(
    RecordAddress::new(FieldName::new("clip"), &[FieldName::new("id")]),
    &[
      Column::new(FieldName::new("id"), "INTEGER", false),
      Column::new(FieldName::new("title"), "TEXT", true),
    ],
  );
}

impl Describe<Db> for Caption {
  const BLUEPRINT: Table = Table::new(
    RecordAddress::new(FieldName::new("caption"), &[FieldName::new("id")]),
    &[Column::new(FieldName::new("id"), "INTEGER", false)],
  );
}

/// `Caption` is described in the SECOND database as well, which is what lets one graph be walked
/// by two visitors that do not agree about where it is stored.
impl Describe<Other> for Caption {
  const BLUEPRINT: Table = Table::new(
    RecordAddress::new(FieldName::new("caption"), &[FieldName::new("id")]),
    &[Column::new(FieldName::new("id"), "int8", false)],
  );
}

/// The graph root, as an expansion writes it: the field list, once, with one
/// [`Describe`](crate::Describe) predicate per field for the walk site to discharge.
struct App;

impl App {
  fn type_iter<V>(v: &mut V) -> Result<(), V::Error>
  where
    V: TypeVisitor,
    Media: Describe<V::Db>,
    Clip: Describe<V::Db>,
    Caption: Describe<V::Db>,
  {
    v.next_type::<Media>()?;
    v.next_type::<Clip>()?;
    v.next_type::<Caption>()
  }
}

/// Every table the walk was shown, in the order it was shown them.
#[derive(Default)]
struct Seen(Vec<&'static str>);

impl TypeVisitor for Seen {
  type Db = Db;
  type Error = core::convert::Infallible;

  fn next_type<E: Describe<Db>>(&mut self) -> Result<(), Self::Error> {
    self.0.push(E::BLUEPRINT.address().table().as_str());
    Ok(())
  }
}

/// A visitor that refuses at a named table — what a walk does after a refusal is the fact under
/// test, and a visitor that could not refuse could not state it.
struct Refuses {
  at: &'static str,
  seen: Vec<&'static str>,
}

impl TypeVisitor for Refuses {
  type Db = Db;
  type Error = &'static str;

  fn next_type<E: Describe<Db>>(&mut self) -> Result<(), &'static str> {
    let table = E::BLUEPRINT.address().table().as_str();
    if table == self.at {
      return Err(table);
    }
    self.seen.push(table);
    Ok(())
  }
}

/// The whole of what a walk owes: each declared node ONCE, in the order the root's fields are
/// written.
#[test]
fn the_walk_hands_over_every_node_once_in_declaration_order() {
  let mut seen = Seen::default();
  App::type_iter(&mut seen).expect("this visitor refuses nothing");
  assert_eq!(seen.0, ["media", "clip", "caption"]);
}

/// A refusal ENDS the walk. What a caller is told is the first node the visitor could not serve, and
/// the nodes after it are not visited — which is what makes a create refuse a graph rather than
/// half-create one.
#[test]
fn a_refusal_ends_the_walk_and_the_nodes_after_it_are_not_visited() {
  let mut refuses = Refuses {
    at: "clip",
    seen: Vec::new(),
  };
  assert_eq!(App::type_iter(&mut refuses), Err("clip"));
  assert_eq!(
    refuses.seen,
    ["media"],
    "the node before the refusal was visited and the one after it was not"
  );
}

/// The DATABASE is the visitor's, so the same emitted walk serves two of them — and the field list
/// is written once whichever it is driven with.
#[test]
fn one_walk_serves_a_visitor_built_for_either_database() {
  /// The second database's visitor, over the one node described in both.
  #[derive(Default)]
  struct Elsewhere(Vec<&'static str>);

  impl TypeVisitor for Elsewhere {
    type Db = Other;
    type Error = core::convert::Infallible;

    fn next_type<E: Describe<Other>>(&mut self) -> Result<(), Self::Error> {
      self
        .0
        .push(E::BLUEPRINT.columns().flat().expect("a flat descriptor")[0].ty());
      Ok(())
    }
  }

  /// A graph of the ONE node both databases describe.
  fn captions<V>(v: &mut V) -> Result<(), V::Error>
  where
    V: TypeVisitor,
    Caption: Describe<V::Db>,
  {
    v.next_type::<Caption>()
  }

  let mut here = Seen::default();
  captions(&mut here).expect("this visitor refuses nothing");
  assert_eq!(here.0, ["caption"]);

  let mut there = Elsewhere::default();
  captions(&mut there).expect("this visitor refuses nothing");
  assert_eq!(there.0, ["int8"], "the other database's own descriptor");
}