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
//! **B-27 — the page whose nodes were raised ELSEWHERE**: [`Page::into_connection_of`], and the
//! refusal it answers an unfilled slot with.
//!
//! Beside [`super::tests`] rather than inside it, which is this workspace's shape for a seam that
//! arrives after a walk has been proven: the roster a reader walks stays the one it was. Its
//! fixtures are its own for the same reason — one `#[Object]` impl per type is Rust's rule, so a
//! second file measuring a second assembly brings a second output object.
//!
//! # What is under test, and what is stood in for
//!
//! The ASSEMBLY. An interface's page is a projection whose nodes come back from a batched, async
//! gather — neither of the two things `into_connection`'s synchronous `FnMut` is — so the caller
//! does the gather and hands the answers back in the page's own order. What is stood in for is the
//! gather itself: a `Vec<Option<…>>` written by hand, because what a store does is measured where
//! the store is.

use async_graphql::Object;

use super::{Connection, UnraisedPage};
use crate::{
  Cursor, CursorValue, FieldName, OrderDirection, OrderTerm, TermName,
  query::{Edge, Page},
};

/// The order every cursor here is minted under — a real term list, so a cursor's signature is the
/// one an engine would compute for it.
const ORDER: &[OrderTerm] = &[OrderTerm::new(
  TermName::new("title"),
  FieldName::new("title"),
  OrderDirection::Asc,
)];

/// Stands in for an emitted `<I><Db>Cursor`: the one column this fixture's order names.
#[derive(Debug, Clone, PartialEq, Eq)]
struct TitleCursor(String);

impl CursorValue for TitleCursor {
  fn write_cursor(&self, out: &mut Vec<u8>) {
    self.0.write_cursor(out);
  }

  fn read_cursor(bytes: &[u8]) -> Option<Self> {
    String::read_cursor(bytes).map(Self)
  }
}

/// The node a client receives — what the GATHER raised, rather than what the page held.
struct RaisedCue {
  title: String,
}

#[Object(name = "RaisedCue")]
impl RaisedCue {
  async fn title(&self) -> &str {
    &self.title
  }
}

/// A page of `titles`, its rows carrying a projection a client never sees — the shape an interface's
/// page has: shared columns and an address, with the object itself living in a member's own table.
fn page(titles: &[&str]) -> Page<&'static str, TitleCursor> {
  let edges = titles
    .iter()
    .map(|title| {
      Edge::new(
        "the projection this page held",
        Cursor::at(ORDER, vec![Some(TitleCursor((*title).to_owned()))]),
      )
    })
    .collect::<Vec<_>>();
  Page::new(edges, true, false)
}

/// The raised nodes, in the page's own order — what a caller's scatter produces.
fn raised(titles: &[&str]) -> Vec<Option<RaisedCue>> {
  titles
    .iter()
    .map(|title| {
      Some(RaisedCue {
        title: (*title).to_owned(),
      })
    })
    .collect()
}

/// **THE CURSORS TRAVEL UNCHANGED, AND THE NODES ARE THE CALLER's.** Each edge pairs the cursor the
/// engine minted at the row with the object the gather raised for it, so a page assembled this way
/// resumes at exactly the boundary the statement produced.
#[test]
fn the_gathered_nodes_land_on_the_pages_own_cursors() {
  let titles = ["alpha", "beta", "delta"];
  let Ok(assembled): Result<Connection<RaisedCue, TitleCursor>, _> =
    Page::into_connection_of(page(&titles), raised(&titles))
  else {
    panic!("every slot was filled");
  };

  assert_eq!(assembled.edges.len(), 3);
  assert!(assembled.has_next_page);
  assert!(!assembled.has_previous_page);
  for (edge, title) in assembled.edges.iter().zip(titles) {
    assert_eq!(edge.node.title, title);
    assert_eq!(
      edge.cursor,
      Cursor::at(ORDER, vec![Some(TitleCursor(title.to_owned()))]),
      "the cursor is the engine's own, never a re-derivation of it",
    );
  }
}

/// **AN EMPTY PAGE ASSEMBLES** — the boundary a narrowed union reaches most often.
#[test]
fn an_empty_page_is_an_empty_connection() {
  let Ok(assembled): Result<Connection<RaisedCue, TitleCursor>, _> =
    Page::into_connection_of(page(&[]), Vec::new())
  else {
    panic!("there was nothing to fill");
  };

  assert!(assembled.edges.is_empty());
}

/// **A SLOT THE GATHER DID NOT FILL IS REPORTED**, naming how many of how many — a page that
/// silently lost rows is a page whose `hasNextPage` is a lie.
#[test]
fn an_unfilled_slot_refuses_rather_than_shortening_the_page() {
  let titles = ["alpha", "beta", "delta"];
  let mut nodes = raised(&titles);
  nodes[1] = None;

  // A `let else` rather than `expect_err`: a connection carries no `Debug` — async-graphql's own
  // type does not derive one — so the `Err` arm is taken by hand rather than through a helper whose
  // bound is about printing the `Ok` one.
  let Err(refusal) = Page::into_connection_of::<
    RaisedCue,
    super::DefaultConnectionName,
    super::DefaultEdgeName,
  >(page(&titles), nodes) else {
    panic!("a slot arrived empty and the assembly did not say so");
  };
  let refusal: UnraisedPage = refusal;

  assert_eq!(refusal.missing(), 1);
  assert_eq!(refusal.of(), 3);
  assert!(refusal.to_string().contains("1 of 3"), "{refusal}");
}

/// **AND SO IS A SHORT LIST** — a gather that answered for fewer addresses than the page asked about
/// is the same fact arriving one shape earlier.
#[test]
fn a_short_list_of_nodes_is_the_same_refusal() {
  let titles = ["alpha", "beta", "delta"];
  let Err(refusal) = Page::into_connection_of::<
    RaisedCue,
    super::DefaultConnectionName,
    super::DefaultEdgeName,
  >(page(&titles), raised(&titles[..2])) else {
    panic!("one address never came back and the assembly did not say so");
  };
  let refusal: UnraisedPage = refusal;

  assert_eq!(refusal.missing(), 1);
  assert_eq!(refusal.of(), 3);
}