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 THE COMPANION COLUMN BUYS A PAGE — the frame half of the sortable cursor, and the row that
//! is now what refuses one.
//!
//! A suite of its own beside [`super::shadow_tests`], which is the `sortable` word's ORDERED-SCAN
//! half: that one asserts which terms the word moves out of the remainder, and this one asserts
//! which of them a page can RESUME at. The two were one refusal until the emitted row learned to
//! project the companion, and holding them apart is what keeps the scan's own guarantee visible
//! after the page's arrived.
//!
//! The claim underneath every assertion is one sentence: **a companion column's value is a boundary
//! like any other, and what decides whether a backend can resume at one is whether its keyset can
//! BIND a blob** — which is a row of its own beside the one that decides whether its `ORDER BY`
//! means anything over one.

use super::{
  CollectionBoundary, CollectionOrdering, NullPlacement, OrderCapability, PagingOrderError,
  ShadowBoundary, ShadowOrdering, TermRepetition, Unpushable, partition,
};
use crate::{FieldName, OrderDirection, OrderTerm, TermName};

/// A dialect with no array type that orders a binary column bytewise AND binds one — SQLite's and
/// MySQL's answers, which is where the whole remainder used to be and where the page now is.
struct Bytes;

impl OrderCapability for Bytes {
  const NULLS: NullPlacement = NullPlacement::Reachable;
  const REPEATED_TERMS: TermRepetition = TermRepetition::Admitted;
  const COLLECTIONS: CollectionOrdering = CollectionOrdering::Divergent;
  const COLLECTION_BOUNDARY: CollectionBoundary = CollectionBoundary::Unbindable;
  const SHADOWS: ShadowOrdering = ShadowOrdering::Bytewise;
  const SHADOW_BOUNDARY: ShadowBoundary = ShadowBoundary::Bindable;
}

/// A backend that ORDERS a companion column the framework's way and cannot BIND one — the row no
/// shipped backend fills, and the whole reason [`Unpushable::ShadowCursor`] stays in the vocabulary.
///
/// It is the fixture's own answer rather than a shipped one on purpose, exactly as
/// [`Boundaryless`](super::tests) is on the array axis: the two shadow rows are independent, and a
/// frame that could not spell their fourth combination would be a frame reading one row off another.
struct Wordless;

impl OrderCapability for Wordless {
  const NULLS: NullPlacement = NullPlacement::Reachable;
  const REPEATED_TERMS: TermRepetition = TermRepetition::Admitted;
  const COLLECTIONS: CollectionOrdering = CollectionOrdering::Divergent;
  const COLLECTION_BOUNDARY: CollectionBoundary = CollectionBoundary::Unbindable;
  const SHADOWS: ShadowOrdering = ShadowOrdering::Bytewise;
  const SHADOW_BOUNDARY: ShadowBoundary = ShadowBoundary::Unbindable;
}

/// A backend that binds a whole ARRAY and cannot bind a companion — the pair that says the two
/// boundary rows are read separately rather than one off the other.
struct ListsOnly;

impl OrderCapability for ListsOnly {
  const NULLS: NullPlacement = NullPlacement::Reachable;
  const REPEATED_TERMS: TermRepetition = TermRepetition::Admitted;
  const COLLECTIONS: CollectionOrdering = CollectionOrdering::Lexicographic;
  const COLLECTION_BOUNDARY: CollectionBoundary = CollectionBoundary::Bindable;
  const SHADOWS: ShadowOrdering = ShadowOrdering::Bytewise;
  const SHADOW_BOUNDARY: ShadowBoundary = ShadowBoundary::Unbindable;
}

/// The companion column's own name, under the synthesized-column law.
const COMPANION: &FieldName = FieldName::new("__ig_tags_sort__");

/// A term over a collection this backend mirrors into a companion column.
fn shadow(direction: OrderDirection) -> OrderTerm {
  OrderTerm::shadow(TermName::new("tags"), COMPANION, direction)
}

/// A term over a collection kept in a COLUMN of the row — the array axis, for the pairs that need
/// both.
fn array(direction: OrderDirection) -> OrderTerm {
  OrderTerm::array(
    TermName::new("chapters"),
    FieldName::new("chapters"),
    direction,
  )
}

/// An ordinary scalar term, for the sequences that need a tail.
fn term(name: &'static str, direction: OrderDirection) -> OrderTerm {
  OrderTerm::new(TermName::new(name), FieldName::new(name), direction)
}

/// **THE DELIVERABLE.** The very term a page was refused at is a page's with the projection: the
/// frame hands the whole order over, companion term and all.
#[test]
fn a_page_resumes_at_a_companion_term() {
  let terms = [shadow(OrderDirection::Asc), term("id", OrderDirection::Asc)];

  assert_eq!(
    partition::<Bytes>(&terms)
      .paging::<Bytes>()
      .expect("a companion's bytes are a boundary this backend binds"),
    &terms,
    "the whole order, in the sequence it runs"
  );
}

/// **Both polarities**, because a page runs either way over one order and a frame that admitted one
/// direction would be a frame nobody could walk backwards.
#[test]
fn either_polarity_is_the_same_answer() {
  for direction in [OrderDirection::Asc, OrderDirection::Desc] {
    let terms = [shadow(direction), term("id", direction)];
    assert!(
      partition::<Bytes>(&terms).paging::<Bytes>().is_ok(),
      "a boundary is a value, and which way the walk runs is the request's"
    );
  }
}

/// **A backend that cannot BIND a companion is refused BY NAME**, and the sentence names the
/// client's own term and the mechanism rather than saying *unsupported*.
#[test]
fn a_backend_that_cannot_bind_a_companion_refuses_by_name() {
  let terms = [shadow(OrderDirection::Asc), term("id", OrderDirection::Asc)];
  let refused: PagingOrderError = partition::<Wordless>(&terms)
    .paging::<Wordless>()
    .expect_err("this backend's keyset binds no blob");

  assert_eq!(refused.term(), TermName::new("tags"));
  assert_eq!(refused.cause(), Unpushable::ShadowCursor);

  let sentence = refused.to_string();
  assert!(
    sentence.contains("`tags`") && sentence.contains("companion column"),
    "the sentence names the term and the mechanism: {sentence}"
  );
}

/// **The ORDERED SCAN is untouched by the boundary row**, which is the asymmetry
/// [`Unpushable::CollectionCursor`] already carries: the statement takes the term and the RESUME
/// does not. A backend that refuses the page still orders by the companion.
#[test]
fn the_scan_is_whole_where_the_page_is_refused() {
  let terms = [shadow(OrderDirection::Asc)];

  assert!(
    partition::<Wordless>(&terms).is_whole(),
    "the ORDER BY carries it — that is the word's own deliverable"
  );
  assert!(partition::<Wordless>(&terms).paging::<Wordless>().is_err());
}

/// **The two BOUNDARY rows are independent**, which is why they are two: a backend that binds a
/// whole list and no blob is refused at the companion and served at the array, and the fixture that
/// answers the other way round is refused at the array and served at the companion.
#[test]
fn a_companion_boundary_is_not_an_array_boundary() {
  let companion = [shadow(OrderDirection::Asc)];
  let list = [array(OrderDirection::Asc)];

  assert_eq!(
    partition::<ListsOnly>(&companion)
      .paging::<ListsOnly>()
      .expect_err("it binds lists, not blobs")
      .cause(),
    Unpushable::ShadowCursor
  );
  assert!(
    partition::<ListsOnly>(&list).paging::<ListsOnly>().is_ok(),
    "and the array row still answers for the array"
  );

  // `Bytes` is the mirror image: no array to bind, a blob it does.
  assert!(partition::<Bytes>(&companion).paging::<Bytes>().is_ok());
}

/// **The FIRST refused term is the one named**, whichever row refused it — which is
/// [`PagingOrderError`]'s own contract, and it holds across the two boundary rows rather than
/// within each.
#[test]
fn the_named_term_is_the_first_one_the_page_could_not_take() {
  struct Neither;

  impl OrderCapability for Neither {
    const NULLS: NullPlacement = NullPlacement::Reachable;
    const REPEATED_TERMS: TermRepetition = TermRepetition::Admitted;
    const COLLECTIONS: CollectionOrdering = CollectionOrdering::Lexicographic;
    const COLLECTION_BOUNDARY: CollectionBoundary = CollectionBoundary::Unbindable;
    const SHADOWS: ShadowOrdering = ShadowOrdering::Bytewise;
    const SHADOW_BOUNDARY: ShadowBoundary = ShadowBoundary::Unbindable;
  }

  let array_first = [array(OrderDirection::Asc), shadow(OrderDirection::Asc)];
  let shadow_first = [shadow(OrderDirection::Asc), array(OrderDirection::Asc)];

  let first = partition::<Neither>(&array_first)
    .paging::<Neither>()
    .expect_err("neither boundary binds");
  assert_eq!(first.term(), TermName::new("chapters"));
  assert_eq!(first.cause(), Unpushable::CollectionCursor);

  let second = partition::<Neither>(&shadow_first)
    .paging::<Neither>()
    .expect_err("neither boundary binds");
  assert_eq!(second.term(), TermName::new("tags"));
  assert_eq!(second.cause(), Unpushable::ShadowCursor);
}

/// **An order with no companion term is untouched**, so the row above is about the one term and not
/// about orders that happen to mention a record with a sortable collection.
#[test]
fn a_page_with_no_companion_term_is_untouched() {
  let terms = [term("id", OrderDirection::Asc)];

  assert_eq!(
    partition::<Wordless>(&terms)
      .paging::<Wordless>()
      .expect("nothing about this order names a companion"),
    &terms
  );
}

/// **A term in the REMAINDER still refuses first**, and with the statement's own cause: a backend
/// that cannot order a companion bytewise never reaches the boundary question at all.
#[test]
fn the_statements_refusal_outranks_the_boundarys() {
  struct Divergent;

  impl OrderCapability for Divergent {
    const NULLS: NullPlacement = NullPlacement::Reachable;
    const REPEATED_TERMS: TermRepetition = TermRepetition::Admitted;
    const COLLECTIONS: CollectionOrdering = CollectionOrdering::Divergent;
    const COLLECTION_BOUNDARY: CollectionBoundary = CollectionBoundary::Unbindable;
    const SHADOWS: ShadowOrdering = ShadowOrdering::Divergent;
    const SHADOW_BOUNDARY: ShadowBoundary = ShadowBoundary::Bindable;
  }

  let terms = [shadow(OrderDirection::Asc)];
  assert_eq!(
    partition::<Divergent>(&terms)
      .paging::<Divergent>()
      .expect_err("the ORDER BY could not carry it")
      .cause(),
    Unpushable::CollectionShadow,
    "the narrower sentence is the statement's, and it is asked first"
  );
}

/// **Every shipped SQL dialect binds one, and MongoDB does not** — the frame's fourth collection
/// table, read off the rows rather than restated.
#[test]
fn the_shipped_rows_answer_as_the_table_says() {
  #[cfg(feature = "sqlite")]
  assert_eq!(
    <sqlx::Sqlite as OrderCapability>::SHADOW_BOUNDARY,
    ShadowBoundary::Bindable
  );
  #[cfg(feature = "postgres")]
  assert_eq!(
    <sqlx::Postgres as OrderCapability>::SHADOW_BOUNDARY,
    ShadowBoundary::Bindable
  );
  #[cfg(feature = "mysql")]
  assert_eq!(
    <sqlx::MySql as OrderCapability>::SHADOW_BOUNDARY,
    ShadowBoundary::Bindable
  );
  #[cfg(feature = "mongo")]
  assert_eq!(
    <crate::Mongo as OrderCapability>::SHADOW_BOUNDARY,
    ShadowBoundary::Unbindable
  );
}