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 — the `sortable` word's read half, proved against the pin.
//!
//! A suite of its own beside [`super::tests`], for the reason the derive's per-word suites give:
//! what is asserted here is ONE word's effect on the frame — which terms it makes pushable, which
//! backend row refuses one, and the page it does NOT yet serve — and holding that apart from the
//! frame's own rows is what keeps a change to either visible.
//!
//! The claim underneath every assertion is one sentence: **a database ordering the companion column
//! bytewise orders the rows the way [`compare_collections`] does.** The encoding half of that is
//! `sort::tests`; this half is that the frame lets the statement carry it.

use super::{
  CollectionBoundary, CollectionOrdering, NullPlacement, OrderCapability, ShadowBoundary,
  ShadowOrdering, TermRepetition, Unpushable, compare_collections, partition,
};
use crate::{
  FieldName, OrderDirection, OrderTerm, TermName, TermSubject, collection_sort_key,
  comparison::sql::SqlOrderError,
};

/// A dialect with no array type that orders a binary column bytewise — SQLite's and MySQL's answers,
/// which is where the whole remainder used to be.
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 whose binary ordering is its own — MongoDB's `BinData`, which ranks by LENGTH before
/// bytes.
struct OtherBytes;

impl OrderCapability for OtherBytes {
  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;
}

/// 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)
}

/// 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 that is a remainder without the word is the STATEMENT's with
/// it, on a dialect that keeps every collection in a table of its own.
#[test]
fn the_word_moves_a_collection_out_of_the_remainder() {
  let edge = [OrderTerm::edge(
    TermName::new("tags"),
    FieldName::new("tags"),
    OrderDirection::Asc,
  )];
  assert_eq!(
    partition::<Bytes>(&edge).cause(),
    Some(Unpushable::CollectionTable),
    "without the word the row has no column to order by"
  );

  let sortable = [shadow(OrderDirection::Asc)];
  assert!(
    partition::<Bytes>(&sortable).is_whole(),
    "with it the order lives entirely in the statement"
  );
}

/// **The term keeps the collection's IDENTITY and renders the COMPANION's name** — which is what
/// lets one written order fingerprint alike on a dialect that keeps a native array and one that
/// keeps a shadow.
#[test]
fn the_two_names_come_apart_exactly_once() {
  let term = shadow(OrderDirection::Asc);
  assert_eq!(term.identity(), TermName::new("tags"));
  assert_eq!(term.column(), COMPANION);
  assert_eq!(term.subject(), TermSubject::Shadow);
  assert!(!term.is_nullable(), "a collection has no null state");
}

/// **A shadow term is a collection and does not bind like one**, which is the split
/// [`TermSubject::binds_the_collection`] exists to keep: its boundary is the companion's own bytes,
/// so the ARRAY row decides nothing about it.
#[test]
fn a_companion_boundary_is_not_an_array_boundary() {
  assert!(TermSubject::Shadow.is_collection());
  assert!(!TermSubject::Shadow.binds_the_collection());
  assert!(TermSubject::Array.binds_the_collection());
}

/// **The BYTES row is what refuses one, never the array row.** The two fixtures differ in
/// [`ShadowOrdering`] alone and agree in [`CollectionOrdering`], so nothing but the new row can be
/// deciding.
#[test]
fn the_bytes_row_is_what_decides_a_companion_term() {
  let terms = [shadow(OrderDirection::Asc)];
  assert!(partition::<Bytes>(&terms).is_whole());
  assert_eq!(
    partition::<OtherBytes>(&terms).cause(),
    Some(Unpushable::CollectionShadow)
  );
}

/// **Every shipped SQL dialect takes one, and MongoDB does not** — the frame's third 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>::SHADOWS,
    ShadowOrdering::Bytewise
  );
  #[cfg(feature = "postgres")]
  assert_eq!(
    <sqlx::Postgres as OrderCapability>::SHADOWS,
    ShadowOrdering::Bytewise
  );
  #[cfg(feature = "mysql")]
  assert_eq!(
    <sqlx::MySql as OrderCapability>::SHADOWS,
    ShadowOrdering::Bytewise
  );
  #[cfg(feature = "mongo")]
  assert_eq!(
    <crate::Mongo as OrderCapability>::SHADOWS,
    ShadowOrdering::Divergent
  );
}

/// **A PAGE at a companion term is SERVED, and the row that could refuse one is a BACKEND's.**
///
/// This assertion used to be the opposite, and what it recorded was a FRAMEWORK gap rather than a
/// fact about the word: an emitted row projected the collection and not its companion, so there was
/// no boundary value to resume at whatever a backend could bind. The page statement now carries the
/// companion under the engine's own sort alias, so what is left is [`ShadowBoundary`] — and a
/// dialect that binds a byte string, which all three do, serves the page.
///
/// The boundary rows and the refusal a downstream backend still gets are
/// [`super::shadow_cursor_tests`]'s; what belongs here is that the WORD costs the scan nothing and
/// now buys the page too.
#[test]
fn a_page_at_a_companion_term_is_served() {
  let terms = [shadow(OrderDirection::Asc), term("id", OrderDirection::Asc)];

  assert!(
    partition::<Bytes>(&terms).is_whole(),
    "the statement carries the whole order — the word's own deliverable"
  );
  assert_eq!(
    partition::<Bytes>(&terms)
      .paging::<Bytes>()
      .expect("and a companion's bytes are a boundary this dialect binds"),
    &terms
  );
}

/// **An ordinary order still pages**, 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::<Bytes>(&terms)
      .paging::<Bytes>()
      .expect("nothing about this order names a companion"),
    &terms
  );
}

/// **The rendered order takes one**, which is the other half of pushability: the frame admitting a
/// term buys nothing if the dialect's own constructor refuses it.
#[cfg(feature = "sqlite")]
#[test]
fn a_dialect_renders_a_companion_term_as_a_plain_column() {
  use crate::{
    Walk,
    comparison::sql::{QueryBuilder, SelectClause, SqlOrder},
  };

  let terms = [shadow(OrderDirection::Asc), term("id", OrderDirection::Asc)];
  let order = SqlOrder::<sqlx::Sqlite>::new(&terms).expect("a companion column is a column");
  let rendered = order
    .push_order_by(
      QueryBuilder::<SelectClause, sqlx::Sqlite>::select()
        .push_field("*")
        .from("t"),
      Walk::Forward,
    )
    .finalize()
    .into_string();

  assert_eq!(
    rendered,
    r#"SELECT * FROM t ORDER BY "__ig_tags_sort__" ASC, "id" ASC"#
  );
}

/// **A backend whose bytes row disagrees is refused at the RENDER too**, and by its own sentence
/// rather than by the null-placement default the map falls through to.
#[test]
fn the_render_names_the_bytes_row() {
  let terms = [shadow(OrderDirection::Asc)];
  let refused = partition::<OtherBytes>(&terms);
  assert_eq!(refused.cause(), Some(Unpushable::CollectionShadow));

  // The SQL family's map is what a downstream dialect's refusal reaches, and the sentence it gets is
  // the one about bytes.
  let message = SqlOrderError::CollectionShadow(TermName::new("tags")).to_string();
  assert!(
    message.contains("companion column") && message.contains("bytewise"),
    "the sentence names the mechanism: {message}"
  );
}

/// **THE PARITY PIN, at the frame's own level.** The order a statement over the companion column
/// produces is the order [`compare_collections`] produces, so the rows a shadow-storing dialect
/// returns and the rows an array-storing one returns are one sequence.
///
/// The statement's ordering is BYTEWISE over the companion, which is what the three SQL rows say, so
/// sorting the encoded keys IS what the engine would do. Holding that against the pin is therefore
/// the whole cross-backend claim, and it is checked over a corpus rather than a pair.
#[test]
fn the_companion_order_and_the_pin_are_one_sequence() {
  let corpus: Vec<Vec<i64>> = vec![
    vec![],
    vec![1],
    vec![1, 2],
    vec![1, 2, 3],
    vec![2],
    vec![9],
    vec![10],
  ];

  let mut by_bytes = corpus.clone();
  by_bytes.sort_by_key(|collection| collection_sort_key(collection));

  let mut by_pin = corpus;
  by_pin.sort_by(|left, right| compare_collections(left, right));

  assert_eq!(
    by_bytes, by_pin,
    "the companion column's bytewise order is the framework's collection order"
  );
}