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 `sortable` COLLECTION CREATES — the companion column, per dialect, and the order a live
//! engine actually returns when it is asked to sort by one.
//!
//! A suite of its own beside [`super::tests`], for the reason the frame's shadow suite gives: what
//! is asserted here is ONE word's effect on the schema — the column, its type, its index and the
//! dialect that declines to build one — and holding that apart from the graph's own statements keeps
//! a change to either visible.
//!
//! # The live half is the deliverable, not the text
//!
//! The rendered statements say what each dialect is SENT. What they cannot say is the one claim the
//! whole word rests on: **that a database ordering the companion column returns the rows in
//! [`compare_collections`](crate::query::compare_collections)'s order.** That is a fact about an
//! ENGINE, so it is measured against one — `mod live`, an in-memory SQLite, where a collection is
//! written into its edge table, its order into the companion beside it, and the rows read back
//! through the framework's own `ORDER BY`.
//!
//! SQLite is the engine the repository can run. The other two dialects reach the same claim through
//! their own [`ShadowOrdering`](crate::query::ShadowOrdering) rows, which are what a reader checks
//! against a server this repository does not provision — the posture the whole SQL family already
//! takes.

#![cfg(any(feature = "sqlite", feature = "postgres", feature = "mysql"))]

use crate::{
  Column, Describe, EdgeShape, EdgeTable, FieldName, RecordAddress, Shadow, Table, TypeVisitor,
  query::sql::Create,
};

/// A record with ONE `sortable` collection: a reel of tags, whose order the row carries beside it.
///
/// One key column, so the statements below are about the companion and not about a key chain.
struct Reel;

/// The collection's path, which its edge table is named from and which its companion names back.
const TAGS: &[&FieldName] = &[FieldName::new("tags")];

/// The companion column, under the SYNTHESIZED-COLUMN law: `__ig_` in front, `__` behind, the
/// field's own name and the word `sort` between them. A declaration cannot spell it — a name with
/// `__` at both ends is refused — so it collides with no column a record could declare, including a
/// field actually called `tags_sort`.
const TAGS_SORT: &FieldName = FieldName::new("__ig_tags_sort__");

const REEL: RecordAddress = RecordAddress::new(FieldName::new("reel"), &[FieldName::new("id")]);

#[cfg(feature = "sqlite")]
impl Describe<sqlx::Sqlite> for Reel {
  const BLUEPRINT: Table = Table::new(
    REEL,
    &[
      Column::new(FieldName::new("id"), "INTEGER", false),
      Column::new(FieldName::new("title"), "TEXT", false),
    ],
  )
  .with_edges(&[EdgeTable::new(TAGS, EdgeShape::Sequence, "TEXT")])
  .with_shadows(&[Shadow::new(TAGS_SORT, TAGS)]);
}

#[cfg(feature = "postgres")]
impl Describe<sqlx::Postgres> for Reel {
  const BLUEPRINT: Table = Table::new(
    REEL,
    &[
      Column::new(FieldName::new("id"), "bigint", false),
      Column::new(FieldName::new("title"), "text", false),
    ],
  )
  .with_edges(&[EdgeTable::new(TAGS, EdgeShape::Sequence, "text")])
  .with_shadows(&[Shadow::new(TAGS_SORT, TAGS)]);
}

#[cfg(feature = "mysql")]
impl Describe<sqlx::MySql> for Reel {
  const BLUEPRINT: Table = Table::new(
    REEL,
    &[
      Column::new(FieldName::new("id"), "BIGINT", false),
      Column::new(FieldName::new("title"), "VARCHAR(255)", false),
    ],
  )
  .with_edges(&[EdgeTable::new(TAGS, EdgeShape::Sequence, "VARCHAR(255)")])
  .with_shadows(&[Shadow::new(TAGS_SORT, TAGS)]);
}

/// The walk a graph root writes, over the one node this suite declares.
fn type_iter<V>(v: &mut V) -> Result<(), V::Error>
where
  V: TypeVisitor,
  Reel: Describe<V::Db>,
{
  v.next_type::<Reel>()
}

/// Every statement the node renders for one dialect, in walk order.
fn schema<Db>() -> Vec<String>
where
  Db: super::AsyncSchemaDialect,
  Reel: Describe<Db>,
{
  let mut create = Create::<Db>::new();
  type_iter(&mut create).expect("this descriptor renders");
  create.statements().to_vec()
}

/// SQLite: a `BLOB` companion, and the index it takes with no key length.
#[cfg(feature = "sqlite")]
#[test]
fn sqlite_creates_a_blob_companion_and_indexes_it() {
  assert_eq!(
    schema::<sqlx::Sqlite>(),
    [
      r#"CREATE TABLE IF NOT EXISTS "reel" ("id" INTEGER NOT NULL, "title" TEXT NOT NULL, "__ig_tags_sort__" BLOB NOT NULL, PRIMARY KEY ("id"))"#,
      r#"CREATE INDEX IF NOT EXISTS "__ig_reel___ig_tags_sort__" ON "reel" ("__ig_tags_sort__")"#,
      r#"CREATE TABLE IF NOT EXISTS "reel_tags" ("id" INTEGER NOT NULL, "tags_ordinal" INTEGER NOT NULL, "tags" TEXT NOT NULL, PRIMARY KEY ("id", "tags_ordinal"))"#,
      r#"CREATE INDEX IF NOT EXISTS "__ig_reel_tags_element" ON "reel_tags" ("id", "tags")"#,
    ]
  );
}

/// PostgreSQL: `bytea`, indexed. The collection is EDGE-STORED here — a native array would order
/// itself and take no companion at all — which is the row the whole per-element strategy decides.
#[cfg(feature = "postgres")]
#[test]
fn postgres_creates_a_bytea_companion_and_indexes_it() {
  assert_eq!(
    schema::<sqlx::Postgres>(),
    [
      r#"CREATE TABLE IF NOT EXISTS "reel" ("id" bigint NOT NULL, "title" text NOT NULL, "__ig_tags_sort__" bytea NOT NULL, PRIMARY KEY ("id"))"#,
      r#"CREATE INDEX IF NOT EXISTS "__ig_reel___ig_tags_sort__" ON "reel" ("__ig_tags_sort__")"#,
      r#"CREATE TABLE IF NOT EXISTS "reel_tags" ("id" bigint NOT NULL, "tags_ordinal" bigint NOT NULL, "tags" text NOT NULL, PRIMARY KEY ("id", "tags_ordinal"))"#,
      r#"CREATE INDEX IF NOT EXISTS "__ig_reel_tags_element" ON "reel_tags" ("id", "tags")"#,
    ]
  );
}

/// MySQL: the same `BLOB` column and NO INDEX over it.
///
/// `ERROR 1170 (42000): BLOB/TEXT column used in key specification without a key length` — so this
/// dialect's [`SORT_KEY_INDEX`](crate::query::sql::AsyncSchemaDialect::SORT_KEY_INDEX) is `false` and the
/// walk emits three statements where the others emit four. The ORDER is unaffected: the column is
/// there and the binary collation ranks it the framework's way; what is lost is a structure the
/// engine could have read pre-sorted.
#[cfg(feature = "mysql")]
#[test]
fn mysql_creates_the_companion_and_declines_the_index() {
  assert_eq!(
    schema::<sqlx::MySql>(),
    [
      r"CREATE TABLE IF NOT EXISTS `reel` (`id` BIGINT NOT NULL, `title` VARCHAR(255) NOT NULL, `__ig_tags_sort__` BLOB NOT NULL, PRIMARY KEY (`id`))",
      r"CREATE TABLE IF NOT EXISTS `reel_tags` (`id` BIGINT NOT NULL, `tags_ordinal` BIGINT NOT NULL, `tags` VARCHAR(255) NOT NULL, PRIMARY KEY (`id`, `tags_ordinal`))",
      r"CREATE INDEX IF NOT EXISTS `__ig_reel_tags_element` ON `reel_tags` (`id`, `tags`)",
    ]
  );
}

/// THE ENGINE'S OWN ANSWER — the claim no rendered statement can make.
#[cfg(feature = "sqlite")]
mod live {
  use sqlx::{Connection as _, Executor as _, Row as _, sqlite::SqliteConnection};

  use super::type_iter;
  use crate::{
    FieldName, OrderDirection, OrderTerm, TermName, Walk, collection_sort_key,
    comparison::sql::{QueryBuilder, SelectClause, SqlOrder},
    query::{
      compare_collections,
      sql::{Create, Validate},
    },
  };

  /// The corpus, in an order that is NOT the answer: the empty collection, a prefix pair, a
  /// first-difference pair, and the `{2}` / `{10}` pair that separates ELEMENT order from stored-text
  /// order.
  ///
  /// The pair that carries the corpus is `["a", "b"]` against `["ab"]`: a JOINED encoding with no
  /// element boundary writes `ab` for both and cannot tell them apart at all, and one with a
  /// separator has to escape it. The frame answers `["a", "b"] < ["ab"]` — the pin's answer, whose
  /// first elements are `"a"` and `"ab"` — and it answers it because the item marker `0x01` is above
  /// the terminator `0x00`.
  fn corpus() -> Vec<(i64, Vec<String>)> {
    let reel = |id: i64, tags: &[&str]| (id, tags.iter().map(|tag| (*tag).to_owned()).collect());
    vec![
      reel(1, &["b"]),
      reel(2, &[]),
      reel(3, &["a", "b"]),
      reel(4, &["a"]),
      reel(5, &["a", "a", "a"]),
      reel(6, &["10"]),
      reel(7, &["2"]),
      reel(8, &["ab"]),
    ]
  }

  /// The schema this suite declares, created for real, and every row of the corpus written into it —
  /// the collection into the edge table and its ORDER into the companion column beside it.
  async fn written() -> SqliteConnection {
    let mut db = SqliteConnection::connect("sqlite::memory:")
      .await
      .expect("an in-memory database");

    let mut create = Create::<sqlx::Sqlite>::new();
    type_iter(&mut create).expect("this descriptor renders");
    create.run(&mut db).await.expect("the schema is created");

    for (id, tags) in corpus() {
      sqlx::query(r#"INSERT INTO "reel" VALUES (?, ?, ?)"#)
        .bind(id)
        .bind(format!("reel {id}"))
        .bind(collection_sort_key(&tags))
        .execute(&mut db)
        .await
        .expect("a reel");
      for (ordinal, tag) in tags.iter().enumerate() {
        sqlx::query(r#"INSERT INTO "reel_tags" VALUES (?, ?, ?)"#)
          .bind(id)
          .bind(i64::try_from(ordinal).expect("a small corpus"))
          .bind(tag)
          .execute(&mut db)
          .await
          .expect("a tag");
      }
    }
    db
  }

  /// The ids the engine returns for an order over the companion column, rendered by the framework's
  /// own `ORDER BY` rather than by a string this test wrote.
  async fn ordered(db: &mut SqliteConnection, walk: Walk) -> Vec<i64> {
    let terms = [
      OrderTerm::shadow(
        TermName::new("tags"),
        FieldName::new("__ig_tags_sort__"),
        OrderDirection::Asc,
      ),
      OrderTerm::new(
        TermName::new("id"),
        FieldName::new("id"),
        OrderDirection::Asc,
      ),
    ];
    let order = SqlOrder::<sqlx::Sqlite>::new(&terms).expect("a companion column is a column");
    let mut built = order
      .push_order_by(
        QueryBuilder::<SelectClause, sqlx::Sqlite>::select()
          .push_field(r#""id""#)
          .from(r#""reel""#),
        walk,
      )
      .finalize();

    built
      .build()
      .fetch_all(db)
      .await
      .expect("the engine answers")
      .iter()
      .map(|row| row.get::<i64, _>(0))
      .collect()
  }

  /// The ids the PIN puts the same corpus in.
  fn pinned() -> Vec<i64> {
    let mut rows = corpus();
    rows.sort_by(|(left_id, left), (right_id, right)| {
      compare_collections(left, right).then(left_id.cmp(right_id))
    });
    rows.into_iter().map(|(id, _)| id).collect()
  }

  /// **THE PARITY PIN, AGAINST A LIVE ENGINE.** SQLite ordering the companion column returns the
  /// corpus in exactly the order [`compare_collections`] does — which is the whole claim the
  /// `sortable` word makes, and the one a rendered statement cannot support.
  ///
  /// Everything about the sequence is the engine's: the bytes came off
  /// [`collection_sort_key`](crate::collection_sort_key) at write time, and nothing in this process
  /// compares them at read time. What the assertion holds them against is Rust's own reading of the
  /// same pin.
  #[tokio::test]
  async fn a_live_engine_orders_the_companion_the_way_the_pin_does() {
    let mut db = written().await;

    assert_eq!(
      ordered(&mut db, Walk::Forward).await,
      pinned(),
      "the engine's order over the companion column is the framework's collection order"
    );
  }

  /// **The BACKWARD walk is the exact reverse**, which is what an order has to be for a page to run
  /// either way over it — the same property the array path's own walk measured on PostgreSQL.
  #[tokio::test]
  async fn the_backward_walk_reverses_it() {
    let mut db = written().await;

    let mut backwards = pinned();
    backwards.reverse();
    assert_eq!(ordered(&mut db, Walk::Backward).await, backwards);
  }

  /// **The empty collection is LEAST and it is a stored row like any other** — one byte in the
  /// companion, not a `NULL`, which is what keeps the null-placement question from arriving at a
  /// column that has no null state.
  #[tokio::test]
  async fn the_empty_collection_sorts_first_and_is_not_null() {
    let mut db = written().await;

    assert_eq!(
      ordered(&mut db, Walk::Forward).await.first().copied(),
      Some(2),
      "the reel with no tags"
    );

    let nulls: i64 =
      sqlx::query_scalar(r#"SELECT COUNT(*) FROM "reel" WHERE "__ig_tags_sort__" IS NULL"#)
        .fetch_one(&mut db)
        .await
        .expect("the engine answers");
    assert_eq!(
      nulls, 0,
      "a collection has no null state and neither has its order"
    );
  }

  /// **The companion column is created, indexed and AUDITED** — where an edge table's columns are
  /// not, the difference being that a companion's name is carried rather than derived.
  #[tokio::test]
  async fn the_companion_is_created_indexed_and_audited() {
    let mut db = written().await;

    let indexes: Vec<String> = sqlx::query_scalar(
      "SELECT name FROM sqlite_schema WHERE type = 'index' AND sql IS NOT NULL ORDER BY name",
    )
    .fetch_all(&mut db)
    .await
    .expect("the catalogue answers");
    assert!(
      indexes
        .iter()
        .any(|name| name == "__ig_reel___ig_tags_sort__"),
      "the companion's index is there: {indexes:?}"
    );

    let mut validate = Validate::<sqlx::Sqlite>::new();
    type_iter(&mut validate).expect("this descriptor renders");
    validate
      .audit(&mut db)
      .await
      .expect("the companion is one of the columns the audit reads");
  }

  /// **A companion the database does not have is DRIFT, named** — the mutation that says the audit
  /// above is reading the column rather than passing everything.
  #[tokio::test]
  async fn a_missing_companion_is_reported_by_name() {
    let mut db = SqliteConnection::connect("sqlite::memory:")
      .await
      .expect("an in-memory database");
    // The same table WITHOUT the companion, which is the schema a deployment written before the word
    // is in.
    db.execute(r#"CREATE TABLE "reel" ("id" INTEGER NOT NULL, "title" TEXT NOT NULL)"#)
      .await
      .expect("a table");

    let mut validate = Validate::<sqlx::Sqlite>::new();
    type_iter(&mut validate).expect("this descriptor renders");
    let drift = validate
      .audit(&mut db)
      .await
      .expect_err("the companion is missing");

    assert!(
      format!("{drift}").contains("__ig_tags_sort__"),
      "the drift names the column: {drift}"
    );
  }
}