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 eight faces on the ABSENT engine — that `()` wears all of them, that each answers what its
//! base impl answers, and that a face and its async twin answer one question alike.

use core::{
  future::Future,
  num::NonZeroUsize,
  pin::pin,
  task::{Context, Poll, Waker},
};

use super::{
  AsyncFulltextRead, AsyncFulltextWrite, AsyncVectorRead, AsyncVectorWrite, FulltextRead,
  FulltextWrite, VectorRead, VectorWrite,
};
use crate::{Connected, FulltextColumn, FulltextSubset, Hits, VectorColumn};

/// Drive a `ready` future to its value without a runtime.
///
/// Hand-rolled rather than taken from an executor crate, exactly as this crate's other seam tests
/// spell it: every future here is already-ready, so what this needs is one poll and a `Waker` that
/// is never woken.
fn block_on<F: Future>(future: F) -> F::Output {
  let mut future = pin!(future);
  let mut cx = Context::from_waker(Waker::noop());
  loop {
    if let Poll::Ready(value) = future.as_mut().poll(&mut cx) {
      return value;
    }
  }
}

/// The `k` every read below hands the verb, spelled once so an assertion reads as a question rather
/// than as a number.
const K: NonZeroUsize = NonZeroUsize::new(10).expect("10 is not zero");

/// The election every `knn` and `get` below names. An absent face holds no column, so which one is
/// named cannot matter — and asserting that it does not is half of what these tests are for.
const COLUMN: VectorColumn = VectorColumn::new("embedding");

/// EVERY FACE DEMANDED AT ONCE, by the compiler.
///
/// The bound is the deliverable: an engine may wear any subset of the eight, and `()` is the citizen
/// that wears all of them — so this instantiation is what would break if a face went missing from
/// the absent engine, at the line naming it rather than at whatever walk first bound one.
///
/// `store::tantivy`'s `audit_row!` is the pattern down to the `const _: fn()` — a bound is resolved
/// where a generic item is INSTANTIATED, so the call never has to happen for the question to be
/// asked.
fn wears_every_face<E>()
where
  E: VectorRead + AsyncVectorRead + VectorWrite + AsyncVectorWrite,
  E: FulltextRead + AsyncFulltextRead + FulltextWrite + AsyncFulltextWrite,
{
}

const _: fn() = wears_every_face::<()>;

/// The absent vector read: both verbs answer EMPTY, which is what the base impl answers and what a
/// store that never indexed anything holds.
#[test]
fn the_absent_vector_read_face_answers_empty() {
  let hits = VectorRead::knn(&(), Connected::new(&(), ()), COLUMN, &[], K, None)
    .expect("the absent face is infallible");
  assert_eq!(hits, Hits::new());

  let vectors = VectorRead::get(&(), Connected::new(&(), ()), COLUMN, &())
    .expect("the absent face is infallible");
  assert!(vectors.is_empty(), "{vectors:?}");
}

/// The absent vector write ACCEPTS the entry and drops it — an index that holds nothing still has to
/// be a legal write target, which is the whole of what this face is for on `()`.
#[test]
fn the_absent_vector_write_face_accepts() {
  VectorWrite::upsert(&(), Connected::new(&(), ()), ()).expect("the absent face is infallible");
}

/// The absent full-text read answers EMPTY for BOTH subset arms, and the pair is the point: a store
/// holding no columns matches no column, so naming one cannot narrow an answer that is already
/// nothing.
#[test]
fn the_absent_fulltext_read_face_answers_empty_for_every_subset() {
  let whole = FulltextRead::search(
    &(),
    Connected::new(&(), ()),
    FulltextSubset::All,
    "car",
    K,
    None,
  )
  .expect("the absent face is infallible");
  assert_eq!(whole, Hits::new());

  let scoped = FulltextRead::search(
    &(),
    Connected::new(&(), ()),
    FulltextSubset::These(&[FulltextColumn::new("body")]),
    "car",
    K,
    None,
  )
  .expect("the absent face is infallible");
  assert_eq!(scoped, whole);
}

/// The absent full-text write accepts the entry and drops it —
/// [`the_absent_vector_write_face_accepts`]'s twin, and the shared write protocol is why the two
/// read alike.
#[test]
fn the_absent_fulltext_write_face_accepts() {
  FulltextWrite::upsert(&(), Connected::new(&(), ()), ()).expect("the absent face is infallible");
}

/// BOTH VECTOR READ FACES ANSWER ONE QUESTION ALIKE.
///
/// The async face delegates to the blocking one, so this is what holds that delegation in place: an
/// async body that answered on its own could drift from the blocking answer with nothing to say so,
/// and one question asked twice is what makes the drift observable.
#[test]
fn both_vector_read_faces_answer_alike() {
  let blocking = VectorRead::knn(&(), Connected::new(&(), ()), COLUMN, &[], K, None)
    .expect("the absent face is infallible");
  let asynchronous = block_on(AsyncVectorRead::knn(
    &(),
    Connected::new(&(), ()),
    COLUMN,
    &[],
    K,
    None,
  ))
  .expect("the absent face is infallible");
  assert_eq!(blocking, asynchronous);

  let blocking = VectorRead::get(&(), Connected::new(&(), ()), COLUMN, &())
    .expect("the absent face is infallible");
  let asynchronous = block_on(AsyncVectorRead::get(
    &(),
    Connected::new(&(), ()),
    COLUMN,
    &(),
  ))
  .expect("the absent face is infallible");
  assert_eq!(blocking, asynchronous);
}

/// Both full-text read faces answer one question alike — [`both_vector_read_faces_answer_alike`]'s
/// twin, over the subset the search is scoped by.
#[test]
fn both_fulltext_read_faces_answer_alike() {
  let subset = FulltextSubset::These(&[FulltextColumn::new("body")]);
  let blocking = FulltextRead::search(&(), Connected::new(&(), ()), subset, "car", K, None)
    .expect("the absent face is infallible");
  let asynchronous = block_on(AsyncFulltextRead::search(
    &(),
    Connected::new(&(), ()),
    subset,
    "car",
    K,
    None,
  ))
  .expect("the absent face is infallible");
  assert_eq!(blocking, asynchronous);
}

/// Both write faces of both families accept alike — the delegation held in place on the direction
/// the read tests do not cover.
#[test]
fn both_write_faces_accept_alike() {
  let blocking = VectorWrite::upsert(&(), Connected::new(&(), ()), ());
  let asynchronous = block_on(AsyncVectorWrite::upsert(&(), Connected::new(&(), ()), ()));
  assert_eq!(blocking.is_ok(), asynchronous.is_ok());

  let blocking = FulltextWrite::upsert(&(), Connected::new(&(), ()), ());
  let asynchronous = block_on(AsyncFulltextWrite::upsert(&(), Connected::new(&(), ()), ()));
  assert_eq!(blocking.is_ok(), asynchronous.is_ok());
}