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 THREE INTERVAL WORDS, RENDERED** — and the assertion is the TEXT, because a bind count
//! cannot tell `overlaps` from `within`.
//!
//! Both words spend four binds against the same four columns; what separates them is which end of
//! the operand each seat is compared against and which way the inequality points. So every case
//! below pins the whole predicate, and the crossed pair is asserted by NAME.

use sqlx::Sqlite;

use super::{SqlTimeRangeComparison, SqlTimeRangedComparison};
use crate::{
  ComplexComparison, CompositeComparison, Contained, ScalarFilter, TimeRange, TimeRangeFilter,
  TimeRanged, TimeRangedFilter, Timestamp, TryFromFilter,
  comparison::sql::{SqlScalarComparison, tests::render},
};

/// The comparison a range filter crosses into, for the one dialect this crate compiles a driver for.
type Crossed = SqlTimeRangeComparison<Sqlite>;

fn at(second: i64) -> Timestamp {
  Timestamp::from_parts(second, 0).expect("an instant")
}

/// The window every assertion below asks about — `[10, 20]`.
fn window() -> TimeRange {
  TimeRange::new(at(10), at(20)).expect("a stretch")
}

fn crossed(filter: TimeRangeFilter) -> Crossed {
  Crossed::try_from_filter(filter).unwrap_or_else(|infallible| match infallible {})
}

/// One range comparison rendered at the column `span` of the harness's row.
fn sql(filter: TimeRangeFilter) -> (String, usize) {
  render::<Sqlite, _>("span", &crossed(filter))
}

/// **AN EMPTY FILTER OPENS NO CONJUNCT.**
#[test]
fn an_empty_filter_crosses_to_an_empty_comparison() {
  let comparison = crossed(TimeRangeFilter::new());

  assert_eq!(ComplexComparison::<Sqlite>::conjuncts(&comparison), 0);
  assert_eq!(comparison.overlaps(), None);
  assert_eq!(sql(TimeRangeFilter::new()), (String::new(), 0));
}

/// **`overlaps` IS THE CROSSED PAIR AND IT IS STRICT ON BOTH SIDES** — the column's START against
/// the operand's END, the column's END against the operand's START, and `<`/`>` rather than
/// `<=`/`>=`.
///
/// Two things are asserted at once and both matter. The CROSSING: the uncrossed spelling is
/// `within`, which is well-formed SQL binding the same four operands and answering a different
/// question. The STRICTNESS: `<=`/`>=` is the CLOSED reading, which reports two abutting stretches as
/// meeting — a wrong answer no bind count would show. Only the text separates any of them.
#[test]
fn overlaps_compares_each_seat_against_the_other_end_strictly() {
  let (rendered, binds) = sql(TimeRangeFilter::new().with_overlaps(window()));

  assert_eq!(
    rendered,
    "(\"span_start_secs\", \"span_start_nanos\") < (?, ?) AND (\"span_end_secs\", \
     \"span_end_nanos\") > (?, ?)"
  );
  assert!(
    !rendered.contains("<=") && !rendered.contains(">="),
    "an intersection of width zero is empty, so neither comparison admits equality"
  );
  assert_eq!(binds, 4, "two instants, two columns apiece");
  assert_eq!(
    ComplexComparison::<Sqlite>::conjuncts(&crossed(
      TimeRangeFilter::new().with_overlaps(window())
    )),
    2,
    "one word, two inequalities"
  );
}

/// **`contains` A SPAN COVERS, and NEITHER comparison is strict**: the column starts no later than
/// the operand and ends no earlier.
///
/// The equal end is the half-openness showing through a second time — the operand's own end is
/// excluded from the operand too, so `[0, 10)` does contain `[0, 10)`. Containment compares LIKE
/// boundaries, which is why it does not inherit `overlaps`'s strictness.
#[test]
fn contains_a_span_puts_the_operand_inside_the_column() {
  let (rendered, binds) = sql(TimeRangeFilter::new().with_contains(window()));

  assert_eq!(
    rendered,
    "(\"span_start_secs\", \"span_start_nanos\") <= (?, ?) AND (\"span_end_secs\", \
     \"span_end_nanos\") >= (?, ?)"
  );
  assert_eq!(binds, 4);
}

/// **`contains` AN INSTANT IS MEMBERSHIP, and it is the ONE MIXED ROW** — `start <= t AND end > t`.
///
/// The open end is what makes the second comparison strict: an instant AT the column's end is not in
/// the column, so a stored instant belongs to exactly one of two abutting stretches. It is the row a
/// span-shaped operand cannot spell, and the reason `contains` carries two shapes.
#[test]
fn contains_an_instant_is_half_open_membership() {
  let (rendered, binds) = sql(TimeRangeFilter::new().with_contains(at(15)));

  assert_eq!(
    rendered,
    "(\"span_start_secs\", \"span_start_nanos\") <= (?, ?) AND (\"span_end_secs\", \
     \"span_end_nanos\") > (?, ?)"
  );
  assert_eq!(binds, 4, "one instant, bound twice");
  assert!(
    !rendered.contains(">="),
    "membership refuses an instant at the open end"
  );
}

/// **`within` IS `contains` REVERSED** — and the two are told apart by the DIRECTION of the
/// inequalities, not by the columns.
#[test]
fn within_puts_the_column_inside_the_operand() {
  let (rendered, binds) = sql(TimeRangeFilter::new().with_within(window()));

  assert_eq!(
    rendered,
    "(\"span_start_secs\", \"span_start_nanos\") >= (?, ?) AND (\"span_end_secs\", \
     \"span_end_nanos\") <= (?, ?)"
  );
  assert_eq!(binds, 4);
}

/// **THE OPERANDS DIFFER TOO, and a rendered string cannot show it**: `overlaps` binds the window's
/// END against the start column, `contains` binds its START — the crossing, seen in the values
/// rather than in the operators.
#[test]
fn the_two_span_words_differ_in_which_end_each_seat_takes() {
  let overlaps = crossed(TimeRangeFilter::new().with_overlaps(window()));
  let contains = crossed(TimeRangeFilter::new().with_contains(window()));

  assert_eq!(
    overlaps.overlaps().map(TimeRange::end),
    Some(at(20)),
    "the first conjunct of `overlaps` compares the START column against the operand's END"
  );
  assert_eq!(
    contains.contains(),
    Some(&Contained::Span(window())),
    "the first conjunct of `contains` compares the START column against the operand's START"
  );
}

/// **A DEGENERATE SPAN OPERAND IS NOT THE INSTANT SHAPE**, and the rendered operators are what say
/// so — the same `[t, t)` reaches `>=` through the span arm and `>` through the instant arm.
///
/// That difference IS the reason `contains` carries two shapes rather than one: under half-openness
/// a degenerate span is not a position, and a client that means a position has a row to say it with.
#[test]
fn a_degenerate_span_operand_is_not_the_instant_arm() {
  let (span_arm, _) = sql(TimeRangeFilter::new().with_contains(TimeRange::instant(at(15))));
  let (instant_arm, _) = sql(TimeRangeFilter::new().with_contains(at(15)));

  assert!(span_arm.ends_with(">= (?, ?)"), "{span_arm}");
  assert!(instant_arm.ends_with("> (?, ?)"), "{instant_arm}");
  assert_ne!(span_arm, instant_arm);
}

/// **THE TWO ENDS TAKE THE INSTANT'S OWN EIGHT WORDS**, and the row value is the instant's own
/// spelling — a `Timestamp` is two columns, so this is the same form a BARE instant column renders.
#[test]
fn the_component_filters_are_the_instants_own() {
  let (rendered, binds) = sql(
    TimeRangeFilter::new()
      .with_start(ScalarFilter::new().with_gte(at(5)))
      .with_end(ScalarFilter::new().with_lt(at(30))),
  );

  assert_eq!(
    rendered,
    "(\"span_start_secs\", \"span_start_nanos\") >= (?, ?) AND (\"span_end_secs\", \
     \"span_end_nanos\") < (?, ?)"
  );
  assert_eq!(binds, 4);
}

/// **AN INTERVAL WORD AND A COMPONENT FILTER NARROW TOGETHER**, which is what one accumulator
/// threaded through five facets means.
#[test]
fn every_facet_joins_one_conjunction() {
  let filter = TimeRangeFilter::new()
    .with_overlaps(window())
    .with_start(ScalarFilter::new().with_gte(at(5)));

  assert_eq!(
    ComplexComparison::<Sqlite>::conjuncts(&crossed(filter.clone())),
    3
  );

  let (rendered, binds) = sql(filter);
  assert_eq!(binds, 6);
  assert!(rendered.contains(" AND "));
  assert_eq!(rendered.matches(" AND ").count(), 2);
}

/// **THE WIDTH IS THE STORAGE MODULE'S**, read rather than restated — four leaves under two parts.
#[test]
fn the_comparison_states_the_columns_the_type_spans() {
  const SEGMENTS: &[crate::ColumnShape] =
    <SqlTimeRangeComparison<Sqlite> as CompositeComparison<Sqlite>>::SEGMENTS;

  assert_eq!(SEGMENTS.len(), 2, "two parts");
  assert_eq!(crate::width(SEGMENTS), 4, "four leaves");
  assert_eq!(SEGMENTS, <TimeRange as crate::ColumnKind>::SEGMENTS);
}

/// **THE TIMED PAIR: the range at the address it was given, the payload one segment below** — which
/// is what flattening one half and naming the other looks like once it is rendered.
#[test]
fn a_timed_payload_applies_the_range_flat_and_the_payload_named() {
  type Payload = SqlScalarComparison<i64, Sqlite>;
  type Timed = SqlTimeRangedComparison<i64, Payload, Sqlite>;

  let filter = TimeRangedFilter::new()
    .with_range(TimeRangeFilter::new().with_overlaps(window()))
    .with_data(ScalarFilter::<i64>::new().with_eq(7i64));

  let comparison = Timed::try_from_filter(filter).expect("the crossing");
  let (rendered, binds) = render::<Sqlite, _>("heard", &comparison);

  assert_eq!(
    rendered,
    "(\"heard_start_secs\", \"heard_start_nanos\") < (?, ?) AND (\"heard_end_secs\", \
     \"heard_end_nanos\") > (?, ?) AND \"heard_data\" = ?"
  );
  assert_eq!(binds, 5);
  assert_eq!(ComplexComparison::<Sqlite>::conjuncts(&comparison), 3);
}

/// **THE TIMED WIDTH IS `TimeRanged<P>`'s**, which is what the payload parameter is carried FOR — a
/// scalar payload is one leaf under `data`, so the pair is five columns.
#[test]
fn the_timed_comparison_states_its_own_width() {
  type Timed = SqlTimeRangedComparison<i64, SqlScalarComparison<i64, Sqlite>, Sqlite>;
  const SEGMENTS: &[crate::ColumnShape] = <Timed as CompositeComparison<Sqlite>>::SEGMENTS;

  assert_eq!(crate::width(SEGMENTS), 5);
  assert_eq!(
    SEGMENTS,
    <TimeRanged<i64> as crate::ColumnKind>::SEGMENTS,
    "the comparison reads the type's own row rather than restating it"
  );
}

/// **AN EMPTY TIMED FILTER OPENS NO CONJUNCT**, on either half.
#[test]
fn an_empty_timed_filter_renders_nothing() {
  type Timed = SqlTimeRangedComparison<i64, SqlScalarComparison<i64, Sqlite>, Sqlite>;

  let comparison =
    Timed::try_from_filter(TimeRangedFilter::<ScalarFilter<i64>>::new()).expect("the crossing");

  assert_eq!(ComplexComparison::<Sqlite>::conjuncts(&comparison), 0);
  assert_eq!(
    render::<Sqlite, _>("heard", &comparison),
    (String::new(), 0)
  );
}