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
//! The two halves of a gather that need no database: the grouping, and the arithmetic that says the
//! batch is never split.
//!
//! What a STATEMENT renders is asserted beside the engine's other statements, over the fixture that
//! implements the whole binding by hand — see [`find`](super::super::find)'s tests.

use super::distribute;

/// A gathered row, standing for what a driver hands back: a parent key, and one element.
///
/// The engine's own decode goes through `sqlx::Row`, and this deliberately does not — what
/// [`distribute`] is given is a slice of whatever the crossing decodes from, so a plain struct is
/// the honest stand-in and keeps this file free of a dialect.
struct Gathered {
  parent: i64,
  element: &'static str,
}

/// A page row: its key, and the collection materialization fills.
#[derive(Debug, PartialEq, Eq)]
struct Page {
  key: i64,
  tags: Vec<&'static str>,
}

impl Page {
  const fn empty(key: i64) -> Self {
    Self {
      key,
      tags: Vec::new(),
    }
  }
}

/// Run the grouping over `page` and `gathered`, decoding both halves infallibly.
fn run(page: &mut [Page], gathered: &[Gathered]) {
  distribute(
    page,
    gathered,
    |row| row.key,
    |row| Ok(row.parent),
    |row| Ok(row.element),
    |row| &mut row.tags,
  )
  .expect("neither half of this fixture can refuse");
}

/// Each parent gets ITS OWN elements, in the order they arrived — which is the order the statement's
/// `ORDER BY` put them in, and therefore the stored sequence.
#[test]
fn every_parent_gets_its_own_elements_in_arrival_order() {
  let mut page = [Page::empty(1), Page::empty(2)];
  run(
    &mut page,
    &[
      Gathered {
        parent: 1,
        element: "a",
      },
      Gathered {
        parent: 2,
        element: "x",
      },
      Gathered {
        parent: 1,
        element: "b",
      },
      Gathered {
        parent: 2,
        element: "y",
      },
    ],
  );
  assert_eq!(page[0].tags, ["a", "b"]);
  assert_eq!(page[1].tags, ["x", "y"]);
}

/// A parent with NO gathered row keeps the empty collection — the collapse, held by the shape of
/// the loop rather than by a backfill step.
///
/// It is the same value the parent whose edge table holds nothing for it should have, so *this
/// collection is empty* and *this parent has no rows* are one answer here and never two.
#[test]
fn a_parent_with_no_gathered_row_keeps_the_empty_collection() {
  let mut page = [Page::empty(1), Page::empty(2), Page::empty(3)];
  run(
    &mut page,
    &[Gathered {
      parent: 2,
      element: "only",
    }],
  );
  assert_eq!(
    page,
    [
      Page::empty(1),
      Page {
        key: 2,
        tags: vec!["only"]
      },
      Page::empty(3),
    ]
  );
}

/// Duplicate elements survive as duplicates — a sequence preserves them, and a grouping that used a
/// set would silently answer a different question.
#[test]
fn a_repeated_element_is_kept_twice() {
  let mut page = [Page::empty(7)];
  run(
    &mut page,
    &[
      Gathered {
        parent: 7,
        element: "dup",
      },
      Gathered {
        parent: 7,
        element: "dup",
      },
    ],
  );
  assert_eq!(page[0].tags, ["dup", "dup"]);
}

/// A gathered row naming a parent the page does not hold is DROPPED rather than refused.
///
/// The engine's own membership cannot produce one — it is exactly the page's keys — so what this
/// pins is that a second writer's row arriving between the two statements leaves the page the set of
/// rows the page statement returned.
#[test]
fn a_gathered_row_for_a_parent_off_the_page_is_ignored() {
  let mut page = [Page::empty(1)];
  run(
    &mut page,
    &[
      Gathered {
        parent: 99,
        element: "elsewhere",
      },
      Gathered {
        parent: 1,
        element: "here",
      },
    ],
  );
  assert_eq!(page[0].tags, ["here"]);
}

/// The NO-CHUNK derivation, as arithmetic rather than as a hope.
///
/// A page is clamped to the framework's ceiling before any statement renders, and the gather binds
/// one parameter per key column per page row. So the widest batch a lane can produce is
/// `MAX_PAGE_SIZE × <key columns>`, and against the LOWEST of the three dialect ceilings that stays
/// under it for every key of 32 columns or fewer — which is why the refusal beside this is a guard
/// for a key nothing declares rather than a case the engine takes.
#[cfg(feature = "sqlite")]
#[test]
fn a_page_of_the_widest_size_stays_under_every_dialect_ceiling() {
  use crate::{comparison::sql::BindCeiling, query::MAX_PAGE_SIZE};

  const WIDEST_KEY: usize = 32;
  let page = MAX_PAGE_SIZE as usize;

  assert_eq!(
    <sqlx::Sqlite as BindCeiling>::MAX_BIND_PARAMETERS,
    32766,
    "the lowest of the three, and the one the derivation is against"
  );
  assert!(
    page * WIDEST_KEY <= <sqlx::Sqlite as BindCeiling>::MAX_BIND_PARAMETERS,
    "a full page of 32-column keys binds under SQLite's ceiling"
  );
  assert!(
    page * (WIDEST_KEY + 1) > <sqlx::Sqlite as BindCeiling>::MAX_BIND_PARAMETERS,
    "and 32 is the LAST width that does, so the number in the note is the exact one"
  );

  #[cfg(feature = "postgres")]
  assert_eq!(<sqlx::Postgres as BindCeiling>::MAX_BIND_PARAMETERS, 65535);
  #[cfg(feature = "mysql")]
  assert_eq!(<sqlx::MySql as BindCeiling>::MAX_BIND_PARAMETERS, 65535);
}